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This is a guide to help you understand how you can port Sailfish OS to devices running Android™ OS. 


Warning: Modifying or replacing your device’s software may void your device’s warranty, lead to data loss, 
hair loss, financial loss, privacy loss, security breaches, or other damage, and therefore must be done entirely 


at your own risk. No one affiliated with this project is responsible for your actions but yourself. Good luck. 
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CHAPTER 
ONE 


OVERVIEW 


1.1 Goal 


By following this guide you can set up a Sailfish OS (or another Sailfish Core based) Linux system that will run 
on an Android device, on top of an existing Android Hardware Adaptation kernel and drivers. 


This consists of: 
e Sailfish Core: the GNU/Linux userspace core 
¢ Android Hardware Adaptation (HA/HAL), consisting of: 
e Device-specific Android Kernel 
e Android base which can be: 
e LineageOS - https://wiki.lineageos.org 
e AOSP - Android Open Source Project - https://source.android.com 
e CAF - Code Aurora Forum - https://www.codeaurora.org 
e Sony Open Devices program - https://developer.sony.com/develop/open-devices 
e Vendor-specific Android base 
e Binary device drivers taken from an Android base 
e Hybris patches to the Android base 
e The libhybris interface built against the binary drivers 
e Middleware packages depending on hardware-specific plugins 
e A Qt/Wayland QPA plugin utilizing the Android hwcomposer 
e Sailfish OS components 


1.2 Development 


1.2.1 Requirements 


The development environment uses the Platform SDK, with: 


e Build Tools consisting of cross-compilers (tooling) and an emulated rootfs for your device architecture (tar- 
get), containing device-specific headers and libraries — will also be referred as build environment through- 
out the document 


e a HA build SDK (a minimal Ubuntu chroot required to build the Android sources) 
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During the HA development you’ll typically have one window/terminal using the HA build SDK where you build 
and work on Android code and another session using the Platform SDK where you build RPMs for the hardware 
adaptation. 


Setting up the Platform SDK, as well as the device-specific build environment and the Ubuntu HA build chroot is 
described in Setting up the SDKs. 


Commands and output from the Platform SDK session are indicated using PLATFORM_SDK $ at the top of the 
code block, like this: 


PLATFORM SDK $ 


echo "run this command in the Platform SDK terminal" 


How to enter PLATFORM_SDK $ is explained in Setup the Platform SDK. 


Commands and output from the HA build session are indicated using HABUILD_SDK $ at the top of the code 
block, like this: 


HABUILD_SDK $ 


echo "run this command in the Ubuntu HA build SDK terminal" 


How to enter HABUILD_SDK $ is explained in Entering Ubuntu Chroot. 


1.2.2 The build area root directory 


In this guide, we refer to the SDK directory hosting Platform SDK, Build Tools, and Ubuntu chroot with the 
environment variable SPLATFORM_SDK_ROOT. You need around 10GB of space in total. 


1.2.3 Build components 
There are a number of components to build; the lower level and Android related components are built in the HA 
build SDK; the rest are built in the Platform SDK. 
+ In the HA build SDK 
e a kernel 
e a hacking friendly initrd which supports various boot options 
e hybris-boot.img and hybris-recovery. img (for booting and debugging) 
e a minimal Android /system/ tree 


e modified Android parts for compatibility with libhybris and Sailfish OS (e.g. Bionic libc, 
logcat, init,...) 


e In the Platform SDK 
e RPM packages containing all the built binaries and extracted configs 
e Hardware-specific middleware and plugins (e.g. Qt QPA plugins, PulseAudio) 


For distribution, RPM packages are uploaded to a HA-specific repository. With this repository, full system images 
using the mic utility. The mic utility is usually also run inside the Platform SDK. 


1.3 Deployment 


The hybris-boot . img (containing both the kernel and our custom initrd) is flashed to the device, while the 
Sailfish OS rootfs is placed in a subdirectory of the /data/ partition alongside an existing, unmodified Android 
system. 
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The Sailfish OS rootfs is then used as a switchroot target with /data bind-mounted inside it for shared access to 
any user data. 
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CHAPTER 
TWO 


PREREQUISITES 


2.1 Mobile Device 


e An Android device officially supported by LineageOS 15.1 (Android 8), 16.0 (Android 9) and 17.1 (Android 
10) at the time of writing 2021-02-12. CyanogenMod versions (that are Sailfish OS-compatible) 10.1.x, 
11.0, 12.1, 13.0, 14.1 will require additional effort because CM has become obsolete. For more supported 
Android versions also check this link 


Throughout this guide we shall use the term Android base, which will refer to the appropriate 
base that you are porting on: LineageOS, AOSP, CAF etc 


We also support Sony Open Devices program, and published guidelines how to rebuild flashable 
images for: 


e Xperia X (Sony AOSP 6) 
e Xperia XA2 (Sony AOSP 8) 
e Xperia 10 (Sony AOSP 9) 
e Xperia 10 II (Sony AOSP 10) 
e Xperia 10 III (Sony AOSP 11) 
Starting with Sailfish OS 3.4.0, support for 64bit ARM SFOS userspace has been added 


Sailfish OS adaptations starting with CM 13.0 (Android 6) were constructed by running a mix of 
64bit Linux Kernel and Android HAL, whilst Sailfish OS userspace was being run in the 32bit 
mode. Such mixed mode is still supported, but we encourage porters to switch to full 64bit ports 
(using Xperia 10 Il as reference) 


See https://wiki.lineageos.org/devices for a list of compatible devices 


See https://wiki.merproject.org/wiki/Adaptations/libhybris for a status list of devices already 
ported using HADK 


See https://wiki.merproject.org/wiki/Adaptations/libhybris/porters for a list of ports in early 
stages, and their authors to contact on the IRC 


AOSP or CAF Android base support is also possible, but we choose LineageOS for a wider 
range of devices. It will be up to the porter to patch an AOSP/CAF base with hybris patches. 
Remaining differences in using it are minimal (e.g. using the lunch command instead of 
breakfast) 


e Means to do backup and restore of the device contents (e.g. SD card or USB cable to host computer), as 
well as flash recovery images to the device 


2.2 Build Machine 


e A 64-bit x86 machine with a 64-bit Linux kernel 
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e Sailfish OS Platform SDK (installation explained later) 


e At least 30 GiB of free disk space (20 GiB source download + more for building) for a complete Android 
6 build; a minimal download and HADK build (only hardware adaptation-related components) requires 
slightly less space. Newer Android base versions yield increasingly bigger size requirements. 


e At least 4 GiB of RAM (the more the better) 
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CHAPTER 
THREE 


PREPARING YOUR DEVICE 


Verify that you can backup and restore your device and that you understand device recovery options. This is not 
only useful when flashing images you build with this guide, but also in case you want to reset your device to its 
factory state with stock Android (note that not all Android vendors provide factory images for download, so you 
might need to create a full backup of your running Android system and store it in a safe place before starting to 
erase and reflash the device with your custom builds). 


3.1 Backup and Verify Your Device 


As mentioned above, it might be helpful to backup the existing stock Android image before flashing the Android 
base release for the first time, as obtaining the stock image might be hard for some vendors (e.g. some stock images 
are only available as self-extracting .exe package for Windows) or impossible (some vendors do not provide stock 
images for download). 


Use Android Recovery (e.g. TWRP or ClockworkMod) to: 
1. Backup to SD card: system, data, boot and recovery partitions 


2. Test restoring the backup (important) 


Warning: While backing up to internal device storage is possible for some devices, if during porting you end 
up overwriting that partition, your backups will be gone. In that case (and in case of devices without SD card 


slots), it’s better to also copy the backup data to your development machine (e.g. via adb pull in recovery). 
Recent versions of adb support full-device backups to a host computer using the adb backup feature. 





See the ClockworkMod Instructions for additional help. 


3.2 Flash and Test your Android base image 


Flash an image that you built or obtained of your Android base, whether it’s LineageOS, CAF, AOSP, or another. 
The official LineageOS flashing instructions can be found on this LineageOS wiki page. 


You may also want to verify that the Android base build for your device is fully functional, to avoid wasting time 
with hardware adaptations that have known issues. Also, your device might have some hardware defects - testing 
in Android verifies that all components are working correctly, so you have a functionality baseline to compare 
your Sailfish OS build results with. 


You should at least check the following features: 
e OpenGL ES 2.0: Use e.g. Gears for Android to test (the hz you will get there will be max refresh rate). 
e WLAN connectivity: Connect to an AP, ad-hoc or set up a mobile access point with your device. 


e Audio: Headset detection, earpiece speaker, loudspeakers, etc. 
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Bluetooth: Connect to bluetooth headsets, verify discoverability, send files. 


NFC: Check if NFC tags can be detected, read and/or written by the device. 


SD/MicroSD: Use a file manager app to see if inserted SD cards can be detected. 


USB: MTP, mass storage (if available) and adb access. 


Telephony: 2G/3G/LTE calls + data connectivity. 
GPS: Using GPS Test, check GLONASS too; typical time to fix; AGPS. 


Sensors: Using AndroSensor: Accelerometer, Proximity Sensor, Ambient Light Sensor, Gyroscope, Mag- 
netometer (Compass), Hall (flip case), ... 


LEDs: If your device has notification LEDs or keypad backlights. 


Camera (front and back): Also test functionality of zoom, flash, etc.. 


Buttons: Volume up, volume down, power, camera shutter, etc.. 


Video out: HDMI / MHL connectivity if you have the necessary adapters. TV out. 


Screen backlight: Suspend and backlight control, minimum and maximum brightness. 


Battery meter: Charge level, battery health, charging via USB (wall charger and host PC). 


Vibration motor: Intensity, patterns. 


HW composer version: check dumpsys SurfaceFlinger through ADB (see SF Layer Debugging). 


Fingerprint sensor 


FM Radio 


We recommend that you write down the results of these tests, so you can always remember them. 
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CHAPTER 
FOUR 


SETTING UP THE SDKS 


4.1 Setting up required environment variables 


Throughout this guide we will be referencing the location of your SDK, device build environment and source 
code. As is customary with Android hardware adaptations, the device vendor ($ VENDOR) and device codename 
(SDEVICE) are also used, both in scripts and configuration files. Throughout this guide as example, we’ll use 
Nexus 5 (Ige/hammerhead for its vendor/device pair), and port it using CyanogenMod 11.0 version as the 
“Android base”. Thus ensure you read the code snippets carefully and rename where appropriate for your ported 
device/vendor/base. 














Now run the following commands on your host operating system fitting for your device and setup: 


HOST $ 


cat <<'EOF' > SHOME/.hadk.env 

export ANDROID_ROOT="SHOME/hadk" 

export VENDOR="lge" 

export DEVICE="hammerhead" 

# "armv7hl" is still supported, but we encourage to have full 64bit ports 
export PORT_ARCH="aarch64" 

# Uncomment the next line to conveniently build all RPMs in local repo: 
#alias mb2='mb2 --output-dir "${ANDROID_ROOT?}/droid-local-repo/${DEVICE?}"' 
EOF 

















cat <<'EOF' >> SHOME/.mersdkubu.profile 

function hadk() { source SHOME/.hadk.env; echo "Env setup for SDEVICE"; } 
export PS1="HABUILD_SDK [\${DEVICE}] $PS1" 

hadk 

EOF 























This ensures that the environment is setup correctly when you use the ubu-chroot command to enter the 
Android SDK. 


It also creates a function hadk that you can use to set or reset the environment variables. 


4.2 Setup the Platform SDK 


Instructions are found on Sailfish OS docs (“Quick start” section is enough, do not install SDK Targets yet): 
https://docs.sailfishos.org/Tools/Platform_SDK/Installation/ 


Afterwards, temporarily leave the PLATFORM_SDK to topup the newly created ~/ .mersdk.profile with 
necessary commands: 


PLATFORM SDK $ 


exit 


(continues on next page) 
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(continued from previous page) 


HOST $ 


cat <<'EOF' >> SHOME/.mersdk.profile 

function hadk() { source SHOME/.hadk.env; echo "Env setup for SDEVICE"; } 
hadk 

EOF 




















sfossdk 


You'll need some tools which are not installed into the Platform SDK by default: 
e android-tools-hadk contains tools and utilities needed for working with the Android SDK 
e kmod is needed by mic’s qemu to build the image 


* createrepo_c is needed when passing local repo to mic 


PLATFORM SDK $ 


sudo zypper ref 
sudo zypper in android-tools-hadk kmod createrepo_c 


The minimum Platform SDK SFOS version is 4.3.0.15. Use sdk-assistant command to upgrade your build 
tools, or create from new (especially when updating from 2.x to 3.x). To check what release you are on: 


PLATFORM_SDK $ 


# if no such file, you're on an old SDK version 
cat /etc/os-releas 





More information about keeping your SDK up-to-date: https://github.com/sailfishos/sdk-setup/blob/master/ 
sdk-setup/README tips. wiki#SDK_Maintenance 


4.3 Setting up an Android Build Environment 


4.3.1 Downloading and Unpacking Ubuntu Chroot 


In order to maintain build stability, we use a Ubuntu GNU/Linux chroot environment from within the Platform 
SDK to build our Android source tree. For Android device ports that require OpenJDK 1.8 or newer, the following 
commands download and unpack the rootfs to the appropriate location: 


PLATFORM SDK $ 


TARBALL=ubuntu-focal-20210531-android-rootfs.tar.bz2 
curl -O https://releases.sailfishos.org/ubu/STARBALL 
UBUNTU_CHROOT=$PLATFORM_SDK_ROOT/sdks/ubuntu 

sudo mkdir -p SUBUNTU_CHROOT 
sudo tar numeric-owner -xjf STARBALL -C SUBUNTU_CHROOT 








In case you find you're not able to gain sudo privileges inside the Ubuntu Chroot, execute the following inside 
the Platform SDK: 


PLATFORM_SDK $ 


sudo chroot $UBUNTU_CHROOT /bin/bash -c "chage -M 999999 $(id -nu 1000)" 





12 Copyright 2014-2022 Jolla Ltd. | Content licensed under CC-BY-NC-SA 3.0 Unported 


v4.3.0.15 Sailfish OS Hardware Adaptation Development Kit Documentation 





4.3.2 Entering Ubuntu Chroot 


PLATFORM SDK $ 
ubu-chroot -r $PLATFORM_SDK_ROOT/sdks/ubuntu 


# FIXME: Hostname resolution might fail. This error can be ignored. 
# Can be fixed manually by adding the hostname to /etc/hosts 





HABUILD_SDK $ 


# Now you are in the HABUILD_SDK environment 
+ To leave, just type `exit or Ctrl+D, and you'll be back to the PLATFORM_SDK 


4.3.3 If your port requires OpenJDK 1.7 or older 


Our ubu-chroot environment is based on 20.04 LTS which provides OpenJDK 1.8 or newer. 


If your Android base build requires an older Java Development Kit, please install the legacy ubu-chroot instead: 


PLATFORM SDK $ 


TARBALL=ubuntu-trusty-20180613-android-rootfs.tar.bz2 
curl -O https://releases.sailfishos.org/ubu/STARBALL 
UBUNTU_CHROOT=SPLATFORM_SDK_ROOT/sdks/ubuntu 

sudo mkdir -p SUBUNTU_CHROOT 
sudo tar numeric-owner -xjf STARBALL -C SUBUNTU_CHROOT 
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CHAPTER 
FIVE 


BUILDING THE ANDROID HAL 


5.1 Checking out Source of the Android base 


Our build process is based around the Android source tree, but where needed we’ve modified some projects, in 
order to apply patches required to make libhybris function correctly, and to minimise the built-in actions and 
services in the init .x.rc files. 


Ensure you have setup your name and e-mail address in your Git configuration: 


HABUILD_SDK $ 


git config --global user.name "Your Name" 
git config --global user.email "you@example.com" 


You also need to install the repo command from the AOSP source code repositories, see Installing repo. 





Note: If your port requires OpenJDK 1.7 or older, use the older repo tool for legacy Python 2 systems. 





After you've installed the repo command, a set of commands below will download the required projects for 
building the modified parts of the Android base used in Sailfish OS hardware adaptations. 


All available Android base variants and versions that you can port on can be seen here: https://github.com/ 
mer-hybris/android/branches 


Choose a version which has the best hardware support for your device. 
Alternatively, you can patch an Android base of your choosing (e.g. be it CAF or AOSP or another). 


The result of your Sailfish OS port will be an installable ZIP file. Before deploying it onto your device, you”1l have 
to flash a corresponding version of the Android base, so Sailfish OS can re-use its Android HAL shared objects. 


If your primary ROM does not match your Android base or its version, and you would like to keep it on your 
device, then look for MultiROM support for it. Starting with its version v28, it supports booting Sailfish OS. 


This porting guide is using Nexus 5 and CyanogenMod 11.0 version as example: 


HABUILD_SDK $ 


sudo mkdir -p SANDROID_ROOT 

sudo chown -R SUSER SANDROID_ROOT 

cd SANDROID_ROOT 

repo init -u git://github.com/mer-hybris/android.git -b hybris-11.0 





5.2 Device repos 


The local manifest contains device-specific repositories, for Android as well as for the mer-hybris builds. 





15 


Sailfish OS Hardware Adaptation Development Kit Documentation v4.3.0.15 





If your device has already been ported, its codes properly placed on GitHub, you should check this repository: 
https://github.com/mer-hybris/local_manifests (choose the branch of hybris-* that your are porting to), and use 
$DEVICE.xml file instead of creating a new one in this chapter. 


Create directory at first: 


HABUILD_SDK $ 


mkdir SANDROID_ROOT/.repo/local_manifests 


If your are working on a new port, you’ ll have to create the local manifest yourself, which contains at least two 
repos: one for the kernel, another for the device configuration. Find those in the LineageOS device wiki, for Nexus 
5 it would be https://wiki.lineageos.org/devices/hammerhead/build#initialize-the-lineageos-source-repository Lo- 
cal manifest below will also need pointing to correct branches - identify which one matches the default manifest 
branch (stable/cm-11.0 in Nexus 5 case). 














Add the following content to SANDROID_ROOT/.repo/local_manifests/SDEVICE. xml: 


<?xml version="1.0" encoding="UTF-8"?> 
<manifest> 
<project path="device/lge/hammerhead" 
name="CyanogenMod/android_device_lge_hammerhead" 
revision="stable/cm-11.0" /> 
<project path="kernel/lge/hammerhead" 
name="CyanogenMod/android_kernel_lge_hammerhead" 
revision="stable/cm-11.0" /> 
</manifest> 























Time to sync the whole source code, this might take a while: 


HABUILD_SDK $ 


repo sync --fetch-submodules 


The expected disk usage for the source tree after the sync is 13 GB (as of 2015-09-09, hybris-11.0 branch). 
Depending on your connection, this might take some time. In the mean time, make yourself familiar with the rest 
of this guide. 


5.3 Configure Mountpoint Information 


Currently in Sailfish OS, udev starts after init rd, which leaves us not being able to use generic partition names 
(independent of partition number). 


In initrd we then have to specify hardcoded /dev/mmcb1kXpY nodes for /boot and /data partitions. 


After initrd, systemd needs to mount all other required partitions (such as /system, /firmware, / 
persist, /config, ...) for the HAL layer to work. The required partitions are read from +. fstab and 
initx*.rc files, disabled there, and respective .mount units created — all done by SANDROID_ROOT/rpm 
(droid-hal-device). 


Unfortunately, sy stemd cannot recognise named partition paths in .mount units, because of the same late start 
of udev, even though one can see already created nodes under /dev/block/platform/*/by-name/ or 
/dev/block/platform/x*/*/by-name. 


To work around this, we need to create a map between partition names and numbers in hybris/ 
hybris-boot/fixup-mountpoints for each device, for all partitions — in this way we are sure to cover 
them all, because if done manually by looking through fstab/rc files, some might get unnoticed. 


To get that mapping, you should flash and boot and image of your Android base and execute adb shell on 
your host and this: 1s -1 /dev/block/platform/x*/by-name/ on your device. In case that yielded 
no results try ls -1 /dev/block/platform/x/x*/by-name/ in some cases you could also try 1s -1 
/dev/block/bootdevice/by-name/. 
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Once you’ve patched fixup-mountpoints, take care if you ever have to run repo sync 
--fetch-submodules again because it will reset your changes, unless the file .repo/ 
local_manifests/$DEVICE.xml is pointing hybris-boot to your fork with the needed fixup- 
mountpoints changes. 











Then when you get to boot to the Sailfish OS UI, please don’t forget to upstream your fixup-mountpoints 
patch. 


5.4 Building Relevant Bits of your Android base 


In the Android build tree, run the following in a bash shell (if you are using e.g. zsh, you need to run these 
commands in a bash shell, as the Android build scripts are assuming you are running bash). 


You'll probably need to iterate this a few times to spot missing repositories, tools, configuration files and others: 


HABUILD_SDK $ 


source build/envsetup.sh 
export USE_CCACHE=1 











breakfast SDEVICE 


make -—j$(nproc --all) hybris-hal droidmedia 


The relevant output bits will be in out /target /product /SDEVICE/, in particular: 











e hybris—boot.img: Kernel and initrd 
e hybris-recovery. img: Recovery boot image 
e system/ and root /: HAL system libraries and binaries 


The approximate size of the output directory out / after make hybris-hal is 10 GB (as of 2019-03-14, 
hybris-sony-aosp-8.1.0_r52-20190206 branch). 


5.4.1 Kernel config 


Once the kernel has built you can check the kernel config. You can use the Mer kernel config checker: 


HABUILD_SDK $ 


cd SANDROID_ROOT 





hybris/mer-kernel-check/mer_verify_kernel_config \ 
./out/target/product /SDEVICE/obj/KERNEL_OBJ/.config 











Apply listed modifications to the defconfig file that your Android base is using. Which one? It’s different for 
every device, most likely first: 





+ Check the value of TARGET_KERNEL_CONFIG under $ANDROID_ROOT/device/$VENDOR/*/BoardConfig*.mk 














e Examine the output of make bootimage for which defconfig is taken when you're building kernel, e.g.: 
mak C kernel/lge/hammerhead ... cyanogenmod_hammerhead_defconfig 





e Check your Android base kernel’s commit history for the arch/armx/configs folder, look for def- 
config 





If you are in a rush, get rid only of ERROR cases first, but don’t forget to come back to the WARNING ones too. 
After you”1l have applied the needed changes, re-run make hybris-boot and re-verify. Lather, rinse, repeat 
:) Run also make hybris-recovery in the end when no more errors. 
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Coniribute your mods back 


Fork the kernel repo to your GitHub home (indicated by myname in this doc). 


For Nexus 5 with CM 11.0 as base, the next action would be (rename where appropriate to match your de- 


vice/branch): 


HABUILD_SDK $ 


cd kernel/lge/hammerhead 
git checkout -b hybris-11.0 








git add $DEFCONFIG 





DEFCONFIG=arch/arm/configs/cyanogenmod_hammerhead_defconfig 


git commit -m "Hybris-friendly defconfig" 
git remote add myname https://github.com/myname/android_kernel_lge_hammerhead 


git push myname hybris-11.0 





Create PR to the forked kernel repo under github/mer-hybris. Ask a mer-hybris admin to create one, if it isn’t 


there. 


Adjust your .repo/local_manifests/$D 











EVIC 





E. xml by replacing the line 





<project path="kernel/lge/hammerhead" 





name="CyanogenMod/android_kernel_lge_hammerhead" 





revision="stable/cm-11.0-XNG3C" /> 


with 





<project path="kernel/lge/hammerhead" 





name="myname/android_kernel_lge_hammerhead" 


revision="hybris-11.0" /> 


5.5 Common Pitfalls 


e If repo sync --fetch-submodules fails with a message like fatal: 


duplicate path 


device/samsung/smdk4412-common in /home/nemo/android/.repo/manifest.xml, remove the local manifest 
with rm .repo/local_manifests/roomservice.xml 


e If you notice git clone commands starting to write out “Forbidden ...” on github repos, you might 
have hit API rate limit. To solve this, put your github credentials into ~/ .netrc. More info can be found 
following this link: Perm.auth. with Git repositories 


e error: Cannot fetch ... (GitError: —force-sync not enabled; cannot overwrite a local work tree., usually 
happens if repo sync --fetch-submodules gets interrupted. It is a bug of the repo tool. Ensure 
all your changes have been safely stowed (check with repo status), and then workaround by: 


HABUILD_SDK $ 


repo sync --force-sync 


repo sync —-fetch-submodules 


e In some cases (with parallel builds), the build can fail, in this case, use make -j1 


... to retry with a 


non-parallel build and see the error message without output from parallel jobs. The build usually ends with 


the following output: 
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HABUILD_SDK $ 


Install: .../out/target/product/$DEVICE/hybris-recovery.img 








Install: .../out/target/product/$DEVICE/hybris-boot.img 
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CHAPTER 
SIX 


INSTALLING BUILD TOOLS FOR YOUR DEVICE 


It is necessary to emulate your target device architecture and file system to build hardware adaptation packages in 
the next section. Download and install your build tools following instructions below. 





Important: Minimum version for SFOS target is 4.3.0.15 (same requirement as for the Platform SDK Chroot 
earlier) 





Warning: To ensure consistency with HADK build scripts, name your tooling SailfishOS—4.3.0 (or 
whichever release you are building for) instead of suggested SailfishOS-latest, and your target as 

















SVENDOR-SDEVICE-SPORT_ARCH (instead of Sai1fishOS-latest-aarch64). Ignore the 1486 tar- 
get. 





For ARM devices, choose aarch64 build target, unless you are building for the armv7h1 Sailfish OS userspace. 
https://docs.sailfishos.org/Tools/Platform_SDK/Target_Installation/ 


To verify the correct installation of the build tools, cross-compile a simple “Hello, World!” C application with 
mb2 build-shell: 


PLATFORM_SDK $ 


cd $HOME 

mkdir hadk-test-tmp 
cd hadk-test-tmp 
cat > main.c << EOF 
#include <stdlib.h> 
#include <stdio.h> 





int main(void) { 
printf("Hello, world!\n"); 
return EXIT_SUCCESS; 





} 
EOF 
mb2 -t SVENDOR-SDEVICE-SPORT_ARCH build-init 

mb2 -t SVENDOR-SDEVICE-SPORT_ARCH build-shell gcc main.c -o test 























If the compilation was successful you can test the executable by running the following command (this will run the 
executable using qemu as emulation layer, which is part of the mb2 setup): 





mb2 -t SVENDOR-SDEVICE-SPORT_ARCH build-shell ./test 











The above command should output “Hello, world!” on the console, this proves that the build tools can compile 
binaries and execute them for your architecture. 
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CHAPTER 
SEVEN 


PACKAGING DROID HAL 


In this chapter, we will package the build results of Building the Android HAL as RPM packages and create a local 
RPM repository. From there, the RPM packages can be added to a local target and used to build libhybris and the 


QPA plugin. They can also be used to build the rootfs. 


7.1 Creating Repositories for a New Device 


If the folders rem, hybris/droid-configs, 


hybris-droid-hal 





version-$DEVICI 





E do not ex- 








1st yet, create them as follows (example is for Nexus 5, adjust as appropriate and push to your GitHub home): 


PLATFORM_SDK $ 


cd SANDROID_ROOT 
mkdir rpm 

cd rpm 

git init 


git submodule add https://github.com/mer-hybris/droid-hal-device dhd 


# Rename 'hammerhead' and other values as appropriate 





sed -e "s/@DEVICE@/hammerhead/" \ 
-e "s/@VENDORG@/l1lge/" \ 
-e "s/@DEVICE_PRETTY@/Nexus 5/" \ 
-e "s/@VENDOR_PRETTY@/LG/" \ 























dhd/droid-hal-@DEVICE@.spec.template > droid-hal-hammerhead. spec 





# Please review droid-hal-hammerhead.spec before committing! 


git add 
git commit -m "[dhd] Initial content" 


# Create this repository under your GitHub home 
git remote add myname https://github.com/myname/droid-hal-hammerhead.git 





git push myname master 
ca. = 


mkdir -p hybris/droid-configs 
cd hybris/droid-configs 
git init 


git submodule add https://github.com/mer-hybris/droid-hal-configs \ 


droid-configs-device 
mkdir rpm 
sed -e "s/@DEVICE@/hammerhead/" \ 
-e "s/@VENDORG@/1lge/" \ 
-e "s/@DEVICE_PRETTY@/Nexus 5/" \ 
-e "s/@VENDOR_PRETTY@/LG/" \ 





























droid-configs-—device/droid-config-@D 
rpm/droid-config-hammerhead.spec 











EVICI 





E@.spec.template > \ 





$ Please review rpm/droid-config-hammerhead.spec befor 


git add 
git commit -m "[dcd] Initial content" 


# Create this repository under your GitHub home 


committing! 


(continues on next page) 
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(continued from previous page) 





git remote add myname https://github.com/myname/droid-config-hammerhead.git 
git push myname master 
cd = 


rpm/dhd/helpers/add_new_device.sh 


patterns/jolla-configuration-hammerhead.yaml 
patterns/jolla-hw-adaptation-hammerhead.yaml 

cd hybris/droid-configs 
COMPOSITOR_CFGS=sparse/var/lib/environment/compositor 

mkdir -p SCOMPOSITOR_CFGS 

cat <<EOF >SCOMPOSITOR_CFGS/droid-hal-device.conf 

# Config for $VENDOR/$DEVICE 

EGL_PLATFORM=hwcomposer 

OT_OPA _PLATFORM=hwcomposer 

# Determine which node is your touchscreen by checking /dev/input/eventx*. WRIT! 
SALL IN ONE LINE(: 

LIPSTICK_OPTIONS=-plugin evdevtouch:/dev/input/event0 -plugin,, 
+evdevkeyboard: keymap=/usr/share/qt5/keymaps/droid.qmap 

EOF 

git add 

git commit -m "[dcd] Patterns and compositor config" 

git push myname master 

(ole = 


# On Nexus 5 the output of the last command is: 
# Creating the following nodes: 

# sparse/ 

# patterns/ 

# 

# 














El 























mkdir -p hybris/droid-hal-version-hammerhead 

cd hybris/droid-hal-version-hammerhead 

git init 

git submodule add https://github.com/mer-hybris/droid-hal-version 

mkdir rpm 

sed -e "s/@DEVICE@/hammerhead/" \ 
-e "s/@VENDORG@/lge/" \ 
-e "s/@DEVICE_PRETTY@/Nexus 5/" \ 
-e "s/@VENDOR_PRETTY@/LG/" \ 
droid-hal-version/droid-hal-version-@DEVICE@.spec.template > \ 
rpm/droid-hal-version-hammerhead.spec 

# Please review rpm/droid-hal-version-hammerhead.spec before committing! 

git add 

git commit -m "[dvd] Initial content" 

# Create this repository under your GitHub home 

git remote add myname \ 
https://github.com/myname/droid-hal-version-hammerhead.git 

git push myname master 












































Now to complete you local manifest, this is how it would be done for Nexus 5. Do it for your device by renaming 
accordingly: 





# add the next 3 entries into .repo/local_manifests/hammerhead.xml 


<project path="rpm/" 








name="myname/droid-hal-hammerhead" revision="master" /> 
<project path="hybris/droid-configs" 
name="myname/droid-config-hammerhead" revision="master" /> 











<project path="hybris/droid-hal-version-hammerhead" 
name="myname/droid-hal-version-hammerhead" revision="master" /> 








Once all these 3 repositories get upstreamed under https://github.com/mer-hybris create PR into an appropriate 
branch of the file .repo/local_manifests/hammerhead. xml to the 
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https://github.com/mer-hybris/local_manifests repository. 


7.2 Packaging droid-hal-device 


The SANDROID_ROOT/rpm/ dir contains the needed . spec file to make a set of RPM packages that form the 
core Droid hardware adaptation part of the hardware adaptation. It also builds a development package (ends with 
-devel) that contains libraries and headers, which are used when building middleware components later on. 


7.2.1 Building the droid-hal-device packages 


The next step has to be carried out in the Platform SDK chroot: 


PLATFORM SDK $ 


cd SANDROID_ROOT 





rpm/dhd/helpers/build_packages.sh droid-hal 
rpm/dhd/helpers/build_packages.sh --configs 
rpm/dhd/helpers/build_packages.sh --mw 
rpm/dhd/helpers/build_packages.sh --gg 
rpm/dhd/helpers/build_packages.sh --version 


This will compile all the needed packages, patterns, middleware and put them under local repository. If anything 
gets modified, just re-run the appropriate part. 


7.2.2 Troubleshoot errors from build_packages.sh 


e Installed (but unpackaged) file(s) found: Add those files to straggler section in your rpm/droid-hal- 
$DEVICE.spec before the Sinclude ... line, for example: 


sdefine straggler_files \ 
/init.mmi.boot.sh\ 
/init.mmi.touch.sh\ 
/init.qcom.ssr.sh\ 
/selinux_version\ 
/service_contexts\ 

S{nil} 





e Then add - droid-hal-hammerhead-detritus to droid-configs/patterns/ 
jolla-hw-adaptation-hammerhead.yaml (substitute as appropriate for your device) 





e Lastly, re-run build_packages.sh droid-hal 
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CHAPTER 
EIGHT 


CREATING THE SAILFISH OS ROOT FILESYSTEM 


8.1 Additional Packages for Hardware Adaptation 


See Middleware for a list of all middleware components (not all middleware components are used by every device 
adaptation). Most of them will have already been built by the build_packages.sh -—-mw script, but if you 
need an extra one, rebuild with rom/dhd/helpers/build_packages.sh -—mw=GIT_URL. 


Via the flexible system of patterns, you will be able to select only working/needed functions for your device. 


8.2 Allowed Content in Your Sailfish OS Image 


The default set of packages results in a minimal and functional root filesystem. 


It is forbidden to add proprietary/commercial packages to your image, because royalty fees need to be paid or 
licence constraints are not allowing to redistribute them. Examples: 


e jolla-xt9 (predictive text input) 

e sailfish-eas (Microsoft Exchange support) 
e aliendalvik (Android™ App Support) 

e sailfish-maps 


e Any non-free audio/video codecs, etc. 


8.3 Patterns 


The selection of packages for each hardware adaptation has to be put into a pattern file, so that creating the image 
as well as any system updates in the future can pull in and upgrade all packages related to the hardware adaptation. 


8.3.1 Modifying a pattern 


To make an extra modification to a pattern, edit its respective file under hybris/droid-configs/ 
patterns/. Take care and always use git status/stash commands. Once happy, commit to your GitHub 
home and eventually PR upstream. 


For patterns to take effect on the image, run the following: 


PLATFORM SDK $ 


cd SANDROID_ROOT 
rpm/dhd/helpers/build_packages.sh --configs 
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8.4 Building the Image with MIC 


You need to choose a Sailfish OS version you want to build. 





Important: Avoid building older releases unless you know what you’re doing - we do not guarantee backwards 
compatibility for old Sailfish OS versions! E.g., expect patterns to break as new HA packages get introduced etc. 


Ensure you pick the same release as your target was in Installing Build Tools for Your Device. E.g., if target’s ssu 
lr versions begin with 4.3.0., build Sailfish OS update 4.3.0.15 (check for the latest, non “Early Access” 
Sailfish OS version) 





Build a rootfs using RPM repositories and a kickstart file (NB: all errors are non-critical as long as you end up 
with a generated .zip image): 


PLATFORM SDK $ 


# Set the version of your choosing, latest is strongly preferred 

# (check with "Sailfish OS version" link above) 

export RELEASE=4.3.0.15 

# EXTRA_NAME adds your custom tag. It doesn't support '.' dots in it! 


export EXTRA_NAME=-myl 


rpm/dhd/helpers/build_packages.sh --mic 



































Once obtained the .zip file, sideload via your device’s recovery mode, or examine other particular ways of 
deploying to your device. 


Jolla Store functionality can be enabled only if your device identifies itself uniquely - either via IMEI or (for 
non-cellular devices) WLAN/BT MAC address. Consult us on #sailfishos-porters IRC channel on oftc.net about 
details. 


If creation fails due to absence of a package required by pattern, note down the package name. 


If that package is critical (e.g. Libhybris, qt5-qpa-hwcomposer-plugin etc.), build and add it to the 
local repo as explained in Additional Packages for Hardware Adaptation. Afterwards perform: 


e Modifying a pattern 
e Building the Image with MIC 


Otherwise if a package is not critical, and you accept to have less functionality (or even unbootable) image, you 
can temporarily comment it out from patterns in hybris/droid-configs/patterns and orderly perform: 


e Modifying a pattern 
e Building the Image with MIC 


Alternatively (or if you can’t find it among patterns) provide a line beginning with dash (e.g. -jolla-camera) 
indicating explicit removal of package, to your .ks Spackages section (remember that regenerating .ks will 
overwrite this modification). 


8.5 Troubleshooting 


8.5.1 /dev/null - Permission denied (while using mic) 


Most likely the partition your Platform SDK resides in, is mounted with nodev option. Remove that option from 
mount rules. 
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8.5.2 Executing commands in the build environment 


You can execute commands to build and install packages under the build environment, inspect and debug any 
issues. The syntax is shown in Installing Build Tools for Your Device. 


Note that mb2 uses a working copy of your original build target, which means you can experiment with mb2 
build-shell at will, but once you have found a desired fix, make it permanent by recording the changes in 
your source code (e.g. do not leave installed packages with zypper in lying around, but add them to your 
.spec’s BuildRequires). 


If you break your build environment viamb2 build-shell, you can reset it back to its clean state viamb2 -t 
SVENDOR-$DEVICE-$PORT_ARCH build-requires reset. This happens implicitly after re-running 
build_packages.sh!. 




















Usemb2 ... build-requires diff if you want to know what you have done to your build environment 
with mb2 in terms of installed/removed packages’. 


mb2 ... build-shell is limited to launch only from directories where you previously ran commands like 
mb2 ... buildormb2 ... build-init?. Such commands are run under SANDROID_ROOT during the 
build of dhd, so you can run mb2 build-shell from SANDROID_ROOT if you find no better place. 











1 As long as your original build target does not change, mb2 keeps using the same working copy (“snapshot” in mb2’s speech) of your build 
target in subsequent executions, preserving any changes you make to it. When your original build target changes, mb2 will reset the working 
copy to match the updated state of your original target next time it is invoked. This happens e.g. when you use build_packages.sh, 
which intentionally works directly on your original build target. Factors that are regarded as a change in the original build target are: RPM DB 
change, SSU configuration, and few other things. 

2 If you need to make permanent changes to the original build environment (not recommended), add --no-snapshot=force option at 
the beginning of mb2 command line (itis a global option). 

3 mb2 looks for a directory named .mb2, where it stores some of its state. It is created implicitly by mb2 ... build and you can also 
create it explicitly with mb2 -t $VENDOR-$DEVICE-$PORT_ARCH build-init. 
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CHAPTER 
NINE 


GETTING IN 


9.1 Boot and Flashing Process 


This varies from device to device. There are a few different boot loaders and flashing mechanisms used for 
Android devices: 


e fastboot: Used by most Nexus devices 
e odin: Used by most Samsung devices 


For flashing fastboot-based devices, use fastboot (available in the Platform SDK), for odin-based devices, use 
Heimdall. 


9.2 Operating Blind on an Existing Device 


Long story short, you will have to assume that you cannot: 
e See any framebuffer console 
e See any error messages of any kind during bootup 
e Get any information relayed from your startup process 
e Set any kind of modified kernel command lines 


Hence, we have to learn how to operate blind on a device. The good news is that when you have a working kernel, 
you can combine it with a init ramdisk and that Android’s USB gadget is built in to most kernel configurations. 
It is possible then for the ramdisk to set up working USB networking on most devices and then open up a telnet 
daemon. 


The hybris-boot repository contains such an initrd with convenient USB networking, DHCP and telnet server, 
plus the ability to boot into a Sailfish OS system. The init system in the hybris-boot initrd will attempt to write 
information via the USB device serial number and model. So dmesg on the host could produce: 


HOST $ 
dmesg # sample output: 


[1094634.238136] usb 2-2: Manufacturer: Mer Boat Loader 
[1094634.238143] usb 2-2: SerialNumber: Mer Debug setting up (DONE_SWITCH=no) 








However dmesg doesn’t report all changes in the USB subsystem and the init script will attempt to update the 
iSerial field with information so also do: 





HOST $ 
lsusb -v | grep iSerial # sample output: 

iSerial 3 Mer Debug telnet on port 23 on rndis0 192.168.2.15 - also running,, 
sudhcpd (continues on next page) 
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(continued from previous page) 


However, if it says something like: 








[1094634.238143] usb 2-2: SerialNumber: Mer Debug setting up (DONE_SWITCH=yes) 


connectivity will be available via telnet 192.168.2.15 2323 port. 


9.3 Logs across reboots 











DEVICE $ 


devel-su 

# change Storage=volatile --> Storage=automatic in: 
vi /etc/systemd/journald.conf 

mkdir /var/log/journal 

reboot 


Systemd suppresses journal, and some valuable info might get hidden. To prevent this, set 
RateLimitInterval=0 


9.3.1 Bootloops 


If device bootloops, there might be several reasons: 


e Ifit immediately reboots (and especially if it later boots to recovery mode), SELinux is enabled, and all ports 
based on Android 4.4 or newer need to disable it. Add CONF IG_SECURITY_SELINUX_BOOTPARAM=y 
to your kernel defconfig, and selinux=0 to your kernel command line (usually in 
BOARD_KERNEL_CMDLINE under $ANDROID_ROOT/device/$ VENDOR/*/BoardConfig*.mk) 























e If it reboots after a minute or so, be quick and telnet into device, then do: 
In -s /dev/null /etc/systemd/system/ofono.service 


e Check if your /system is mounted by systemd (system.mount unit) 


9.3.2 Tips 


To ease debugging in unstable/halting/logs spamming early ports: 





DEVICE $ 











systemctl mask droid-hal-init 
systemctl mask user@100000 


9.3.3 Get connected 


Use USB networking to connect to the Internet from your Sailfish OS 


Execute on your host as root. Use the interface which your host uses to connect to the Internet. It’s wlan0 in this 
example: 


HOST $ 





iptables -t nat -A POSTROUTING -o wlan0 -j MASQUERADE 
echo 1 > /proc/sys/net/ipv4/ip_forward 
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Execute on the device: 


TARGET $ 





route add default gw 192.168.2.X # <- host's usb0O IP 
echo 'nameserver 208.67.222.222' > /etc/resolv.conf 


9.4 Splitting and Re-Assembling Boot Images 


A boot.img file is basically a combination of a Linux kernel and an initramfs as cpio archive. The Platform 
SDK offer the mkboot img to build a boot image from a kernel and cpio archive. To split a boot image, use 
split_boot img in Platform SDK. 


In the Sailfish OS port, a boot image with Sailfish OS-specific scripts will be built automatically. These boot im- 
ages are then available as hybris-boot.img (for booting into Sailfish OS) and hybris-recovery.img (for debugging 
via telnet and test-booting). 
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CHAPTER 
TEN 


FLASHING THE ROOTFS IMAGE 


In order to be able to use Sailfish OS on the device, the parts that we built and assembled in the previous chapters 
now need to be flashed to the device. After flashing, Sailfish OS should boot on your device on the next reboot. 


10.1 Prerequisites 


e Android Recovery flashed to your device 
e The stock firmware image (for your version and device) 
¢ The Android base release (for your version and device) 


e A Sailfish OS rootfs update .zip, created by mic 


10.2 Flashing back to Stock Android 


It is important that you start with a fresh stock image that matches the Android base release version you are going 
to flash (which in turn is dictated by the Sailfish OS image you are going to flash). 


While the Android base (e.g. CyanogenMod) .zip contains all files in /system/ (e.g. libraries and libhardware 
modules), the stock image also contains firmware parts and flashables for partitions that are not included in the 
Android base .zip. 


For example, if you are running stock 4.4.2 on a Nexus 4 (mako), and you are going to flash CM 10.1.3 and 
Sailfish OS to it, you have to first flash the stock 4.2.2 (note that this is 4.2, not 4.4) first, so that the firmware bits 
are matching the CM version. 


If you do not flash the right stock version (and therefore firmware), there might be some issues when booting into 
Sailfish OS: 


e Problems accessing /sdcard/ in recovery (e.g. adb push does not work) 
e WLAN, sensors, audio and other hardware not working 


If you experience such issues, please make sure you first flash the stock system, ROM, followed by the Android 
base image, and finally the Sailfish OS update. Please also note that you can’t just take the latest stock ROM 
and/or Android base ROM - both versions have to match the Android version against which the Sailfish OS 
adaptation was built. 


10.3 Flashing using Android Recovery 


1. Boot into Android Recovery 





2. Upload the CM release: adb push cm-10.1.3-$DEVICE.zip /sdcard/ 




















3. Upload Sailfish OS: adb push sailfishos-$DEVICE-devel-1.2.3.4.zip /sdcard/ 
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. In the Recovery on the device: 

. Clear data and cache (factory reset) 

. Install the CM release by picking the CM image 
. Install Sailfish OS by picking the SFOS image 


. Reboot the device 





36 


Copyright 2014-2022 Jolla Ltd. | Content licensed under CC-BY-NC-SA 3.0 Unported 


CHAPTER 
ELEVEN 


MANUAL INSTALLATION AND MAINTENANCE 


This assumes you are booted into the Android base on your device, can adb shell to it to get a root shell and 
have your boot image and rootfs tarball ready. 


Some of these approaches also work in Android Recovery (there’s an adbd running). 


11.1 Extracting the rootfs via adb 





Replace sailfishos—devel-hammerhead.tar.bz2 with the name of your rootfs tarball: 


PLATFORM SDK $ 


adb push sailfishos-devel-hammerhead.tar.bz2 /sdcard/ 

adb shell 

su 

mkdir -p /data/.stowaways/sailfishos 

tar numeric-owner -xvf /sdcard/sailfishos-devel-hammerhead.tar.bz2 \ 
-C /data/.stowaways/sailfishos 











11.2 Flashing the boot image via adb 


The following example is for hammerhead, for other devices the output partition and filename is obviously 
different: 


PLATFORM SDK $ 


cd SANDROID_ROOT 

adb push out/target/product/hammerhead/hybris-boot.img /sdcard/ 
adb shell 

su 

dd if=/sdcard/hybris-boot.img of=/dev/block/mmcb1k0p19 


11.3 Flashing or booting the boot image via fastboot 


PLATFORM_SDK $ 


cd SANDROID_ROOT 

# to smoke test a boot image without flashing it: 

fastboot boot out/target/product/$DEVICE/hybris-—boot.img 

# to permanently flash an image to boot partition: 

fastboot flash boot out/target/product/$DEVICE/hybris-—boot.img 
adb shell 














(continues on next page) 
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(continued from previous page) 


su 
dd if=/sdcard/hybris-boot.img of=/dev/block/mmcb1k0p19 


11.4 Interacting with the rootfs via adb from Android 


You can interact with the Sailfish OS rootfs and carry out maintenance (editing files, installing packages, etc..) 
when booted into an Android system. You have to have your rootfs already installed/extracted. You can use 
Android's WLAN connectivity to connect to the Internet and download updates: 


PLATFORM_SDK $ 


adb shell 

su 

mount -o bind /dev /data/.stowaways/sailfishos/dev 
mount -o bind /proc /data/.stowaways/sailfishos/proc 
mount -o bind /sys /data/.stowaways/sailfishos/sys 
chroot /data/.stowaways/sailfishos/ /bin/su - 

echo "nameserver 8.8.8.8" >/etc/resolv.conf 





38 Copyright 2014-2022 Jolla Ltd. | Content licensed under CC-BY-NC-SA 3.0 Unported 


CHAPTER 
TWELVE 


OTA (OVER-THE-AIR) UPDATES 


You can setup to upgrade a Sailfish OS device over the air, a.k.a. OTA update. 


12.1 Prepare the infrastructure 


e Ensure your Sailfish OS version is at least 3.2.1 (3.4.0 for aarch64) 


e Create file 20-mydomain.ini (rename “mydomain” as you see fit) under SANDROID_ROOT/ 
hybris/droid-configs/sparse/usr/share/ssu/repos.d/ with the following content: 


[release] 
adaptation=https://mydomain.net/% (release) /% (vendor) -$ (adaptation) /% (arch) / 





Substitute https: //mydomain.net/ with your Web server address (including subpath if exists) 





The $ (release) /% (vendor) -% (adaptation) /% (arch) / format is advised, because it’s the 
most future-proof. E.g. for the Nexus 5 this string would resolve to 4.3.0.15/1ge-hammerhead/ 
aarch64/ 


Commit the above change to droid-configs (including updating the submodule, which introduces times- 
tamped versioning, so updates get picked up) 


Make new image and ensure devices are flashed which will be receiving future updates 


Make some changes to your adaptation (e.g. fix some HW issue) and rebuild the affected part via 
build_packages.sh, so that version numbers increase 


12.2 Test for any breakages 


Before deploying any updates to production, they must be tested first. 
Prerequisites: 
e Web server (e.g. Apache) running on HOST and accessible within network 
e Directory listing doesn’t need to be enabled 
e Assuming Web server’s rootdir is /srv/http 


Perform the following: 


HOST $ 


. “/.hadk.env 

rm -rf /srv/http/sailfish-tmp-test-repo 

cp -ar SANDROID_ROOT/droid-local-repo/SDEVICE /srv/http/sailfish-tmp-test-repo 
rm -rf /srv/http/sailfish-tmp-test-repo/repo 

createrepo_c /srv/http/sailfish-tmp-test-repo 
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SSH into your device and execute (substituting https://mydomain.net with the address to your Web 
server): 





DEVICE $ 











ssu ar sfos-test https://mydomain.net/sailfish-tmp-test-repo 
devel-su -p pkcon install zypper 

devel-su zypper refresh sfos-test 

devel-su zypper dup --from sfos-test 


Check that all the packages you touched are to be updated or removed as expected. Afterwards you can press 
“Yes” to execute the update and check if the device functions as desired, also after reboot. 


Once happy, clean up the testing environment: 





DEVICE $ 











ssu rr sfos-test 


HOST $ 


rm -rf /srv/http/sailfish-tmp-test-repo 


12.3 Release into production for all users 


Once successfully tested, deploy the stable packages to the release repo: 
HOST $ 


=/.hadk.env 
rm -rf /srv/http/SRELEASE/SVENDOR-S$DEVICE/SPORT_ARCH 
mkdir -p /srv/http/SRELEASE/SVENDOR-SDEVICE 
cp -ar SANDROID_ROOT/droid-local-repo/$DEVICE \ 
/srv/http/$RELEASE/SVENDOR-SDEVICE/$PORT_ARCH 
rm -rf /srv/http/SRELEASE/SVENDOR-SDEVICE/SPORT_ARCH/repo 
createrepo_c /srv/http/$RELEASE / SVENDOR-SDEVICE/$PORT_ARCH 





























To receive the update, each device will have to execute devel-su -p version --dup, and reboot when 
instructed. 


12.4 Adding custom RPM packages 


You can add any other RPM binary packages to the local build repository (i.e. packages that were not created by 
running build_packages.sh). For example: 


PLATFORM SDK $ 


cd SANDROID_ROOT 
# Alternatively you can use 'mb2 --output-dir ... build” instead of copying 


cp -a path/to/custom-built.rpm droid-local-repo/SDEVICE 





To make the devices of your users pull this RPM package in, ensure some other package or pattern requires it, 
then fest and deploy your repo as per instructions above. 
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12.5 Updating to the next Sailfish OS release 


If another official Sailfish OS update has been released since you last published your HW adaptation update, 
perform the following: 


Update your SDK target device build environment (see how in the last paragraph of Setup the Platform SDK). 
Alternatively, you can remove it and create a new one as per Installing Build Tools for Your Device. 


Remove or backup your local build repository: 


PLATFORM SDK $ 


cd SANDROID_ROOT 











PREV_RELEASE=4.2.0.21 # adjust to the previous release version you were on 





mv droid-local-repo/SDEVICE droid-local-repo/S$DEVICE-SPREV_RELEASE 
mkdir droid-local-repo/$DEVICE 





Then rebuild all packages and a new image by executing build_packages.sh. 


Afterwards fest the rebuilt repo. The actual testing sequence on the device will be different: 





DEVICE $ 











ssu ar sfos-test https://mydomain.net/sailfish-tmp-test-repo 
ssu dr adaptation0 

ssu re 4.3.0.15 # adjust to the actual version 

devel-su -p version dup 

ssu rr sfos-test 

ssu er adaptation0 





Then reboot as and test device functionality. 
Once satisfactory, publish your repo for all users. 


Finally, to receive the update, each device will have to execute: 





DEVICE $ 











ssu re 4.3.0.15 # adjust to the actual version 
devel-su -p version --dup 


NOTE: The %(release) in your self-hosted repo (visible via ssu 1r) will get updated automatically after ssu 
re. 





After devel-su -p version -—dup has finished, reboot as instructed. 
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CHAPTER 
THIRTEEN 


MODIFICATIONS AND PATCHES 


Running Sailfish OS on top of a Mer Hybris adaptation requires a few modifications to the underlying Android 
base. We maintain forks of some repos with those patches applied. 


13.1 Hybris Modifications to an Android base 


Our modifications are tracked by our own Hybris-specific repo manifest file. The below sections outline our 
modifications to these sources. 


13.1.1 Droid System 


In order to work with 1ibhybris, some parts of the lower levels of Android need to be modified: 
e bionic/ 
e Pass errno from bionic to libhybris (1ibdsyscalls.so) 
e Rename /dev/log/ to /dev/alog/ 
e TLS slots need to be re-assigned to not conflict with glibc 
e Support for HYBRIS_LD_LIBRARY_PATH in the linker 
e Add /usr/libexec/droid-hybris/system/1ib to the linker search path 


e external/busybox/: Busybox is used in the normal and recovery boot images. We need some addi- 
tional features like mdev and udhcpd 


» system/core/ 
e Make cutils and logcat aware of the new log location (/dev/alog/) 
e Add /usr/libexec/droid-hybris/lib-dev-alog/ to the LD_LIBRARY_PATH 


e Force SELinux OFF since hybris does not utilise the relevant Android parts, and leaving 
SELinux support ON would then cause device to reboot to recovery 


e Remove various init and init.rc settings and operations that are handled by systemd 
and/or Hybris on a Sailfish OS system 


e frameworks/base/: Only build servicemanager, bootanimation and androidfw to make the 
minimal Droid HAL build smaller (no Java content) 


¢ libcore/: Don’t include JavaLibrary.mk, as Java won't be available 


All these modifications have already been done in the mer-hybris GitHub organisation of forks from various 
Android sources. If its android manifest is used, these patches will be included automatically. 


In addition to these generic modifications, for some devices and SoCs we also maintain a set of patches to fix 
issues with drivers that only happen in Sailfish OS, for example: 


e hardware/samsung/: SEC hwcomposer: Avoid segfault if registerProcs was never called 





43 


Sailfish OS Hardware Adaptation Development Kit Documentation v4.3.0.15 





13.1.2 Kernel 


For the Kernel, some configuration options must be enabled to support syst emd features, and some configuration 
options must be disabled, because they conflict or block certain features of Sailfish OS. 


e Required Configuration Options: See SANDROID_ROOT/hybris/hybris-boot/init-script 
function check_kernel_config() for a list of required kernel options 


» Conflicting Configuration Options: CONFIG_ANDROID_PARANOID_NETWORK: This would make all 
network connections fail if the user is not in the group with ID 3003. 


As an alternative to checking the kernel options in the initramfs, the script SANDROID_ROOT/hybris/ 
mer-kernel-check can also be used to verify if all required configuration options have been enabled. 





13.2 Configuring and Compiling the Kernel 


For supported devices, the kernel is built as part of mka hybris-hal with the right configuration. 


For new devices, you have to make sure to get the right kernel configuration included in the repository. For 
this, clone the kernel repository for the device into mer-hybris and configure the kernel using hybris/ 
mer-kernel-check. 
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CHAPTER 
FOURTEEN 


DETAILED SUBSYSTEM ADAPTATION GUIDES 


Sailfish OS uses some kernel interfaces directly, bypassing the android HAL. Mainly this is used in places where 
the kernel API is stable enough and also used by Android. The other reasons for using kernel APIs directly 
include better features offered by standard kernel frameworks, differing middleware between Sailfish OS linux 
and Android, and lastly special features of Sailfish OS. 


14.1 Vibration / force feedback 


The default vibra framework that is used in full featured productized Sailfish OS devices is the force feedback 
API in kernel input framework. The kernel drivers should either use the ffmemless framework OR provide 
FF_PERIODIC and FF_RUMBLE support via as a normal input driver. In this chapter we go through the ff- 
memless aproach of adapting your kernel for Sailfish OS 


This is a different method than what is used in community Sailfish OS ports, which utilize the android vibrator / 
timed-output API. The android vibrator plugins in Sailfish OS middleware have very reduced feature set, and are 
not recommended for commercial products. 


In order to utilize the standard input framework force feedback features of Sailfish OS, the android timed output 
vibrator kernel driver needs to be converted to a ffmemless driver. The main tasks for this are: 


e Enable CONFIG_INPUT_FF_MEMLESS kernel config option 
e Disable CONFIG_ANDROID_TIMED_OUTPUT kernel config option 
e Change maximum amount of ffmemless effects to 64 by patching ff-memless.c: 


e http://git.kernel.org/cgit/linux/kernel/git/torvalds/linux.git/tree/drivers/input/ff- memless.ctn41 


diff --git a/drivers/input/ff-memless.c b/drivers/input/ff-memless.c 

index 117a59a..fa53611 100644 

--- a/drivers/input/ff-memless.c 

+++ b/drivers/input/ff-memless.c 

@@ -39,7 +39,7 (QQ MODULE_AUTHOR("Anssi Hannula <anssi.hannula@gmail.com>") ; 
MODULE_DESCRIPTION ("Force feedback support for memoryless devices"); 























/x* Number of effects handled with memoryless devices x/ 
—-#define FF_MEMLESS_EFFECTS 16 
+#define FF_MEMLESS_ EFFECTS 64 























/* Envelope update interval in ms x/ 
#define FF_ENVELOPE_INTERVAL 50 


























e Optionally you can decrease ff-memless control interval so that fade and attack envelopes can be used in 
short haptic effects as well: 


diff --git a/drivers/input/ff-memless.c b/drivers/input/ff-memless.c 
index 89d3a3d..33eee2e 100644 
--- a/drivers/input/ff-memless.c 


(continues on next page) 
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+++ b/drivers/input/ff-memless.c 
@@ -41,7 +41,7 @@ MODULE_DESCRIPTION ("Force feedback support for memoryless devi 
#define FF_MEMLESS EFFECTS 64 





























/*x Envelope update interval in ms */ 
-static int ff_envelope_interval = 50; 
+static int ff_envelope_interval = 10; 
module_param(ff_envelope_interval, int, S_IWUSR | S_IRUGO); 




















#define FF_EFFECT_STARTED 0 














If your platform happens to already support a ffmemless based vibra driver, just enable it and fix any issues 
that you see. Otherwise go through the rest of the points below. 


Convert the android timed output vibra driver to support to ffmemless 


e add “#include <linux/input.h>” 


Create a ffmemless play function. 


Examples of ffmemless play functions / ffmemless drivers: 


http://git.kernel.org/cgit/linux/kernel/git/torvalds/linux. git/tree/drivers/input/misc/ 
arizona-haptics.c#n110 


http://git.kernel.org/cgit/linux/kernel/git/torvalds/linux. git/tree/drivers/input/misc/max8997_ 
haptic.c#n23 | 


http://git.kernel.org/cgit/linux/kernel/git/torvalds/linux. git/tree/drivers/input/misc/ 
pm8xxx-vibrator.c#n 130 


At probe, create a ffmemless device with input_ff_create_memless 


http://git.kernel.org/cgit/linux/kernel/git/torvalds/linux. git/tree/include/linux/input.h#n53 1 


And register the resulting device with input_device_register. 


Remember to clean up the input device structure at driver exit 


The example ffmemless drivers above can be used for reference 


The userspace configuration haptic feedback and effects is handled with ngfd configuration files, see more details 
in 


e Configuring haptics 


14.2 GStreamer v1.0 


Sailfish OS 2.0 introduces GStreamer v1.0 with hardware-accelerated video and audio encoding and decoding in 
Camera, Gallery and Browser, and deprecates GStreamer v0.10. 


The GStreamer-droid bridge is part of the integral build process. If you need to modify its source code, then 
rebuild it via: 


PLATFORM SDK $ 


cd SANDROID_ROOT 
rpm/dhd/helpers/build_packages.sh --gg 
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14.3 Camera 


Launch the Camera app. If if shows black screen and becomes non-responsive, enable the 
audiosystem-passthrough-dummy-af package in the patterns and rebuild droid-configs. 


When the app is working, it will initially be at its default (low) resolution settings and reduced feature set (e.g. no 
flash or focus mode selection). To improve those, install gst reamer1.0-droid-tools on device (RPM is 
available under SANDROID_ROOT/droid-local-repo/$DEVICE/gst-droid/) and launch: 


























DEVICE $ 


devel-su # Set your password in Settings | Developer mode 
mk-cam-conf 0 /etc/gst-droid/gstdroidcamsrc-0.conf 
mk-cam-conf 1 /etc/gst-droid/gstdroidcamsrc-1.conf 


This creates configs for each, front and back cameras. Transfer them over and place under SANDROID_ROOT/ 
hybris/droid-configs/sparse/etc/gst-droid for persistency (don’t forget to git commit+push 
somewhere safe! :) 


Next you’ll need to generate the resolutions file. Build the following repo: 


PLATFORM SDK $ 


cd SANDROID_ROOT 
rpm/dhd/helpers/build_packages.sh mw=droid-camres 











Install the RPM from SANDROID_ROOT/droid-local-repo/S$DEVICE/droid-camres/ onto your de- 
vice and execute: 














DEVICE $ 








droid-camres -w 





# It creates a failsafe jolla-camera-hw.txt, manual perfecting is encouraged 


devel-su # Set your password in Settings | Developer mode 
mv jolla-camera-hw.txt /etc/dconf/db/vendor.d/ 
dconf update 


Go to Settings | Apps | Camera and ensure valid ratio and megapixel entries appear in both cameras. Reloading 
Camera app should effectuate the changes. 


You can further fix/improve the contents of jolla-camera-hw.txt by looking more closely at the output of 
droid-camres. Sometimes it chooses an aspect ratio which provides sub-optimal resolution, e.g. it prefers 
4:3 for the front facing camera, yet sensor only supports 1280x960, however switching to 16:9 would give a far 
superior 1920x1080 resolution. 


This command will list all available parameters for a specific camera from the underlying HAL, which will help 
with tweaking values such as ISO speed, focus and flash: 





GST_DEBUG=6 mk-cam-conf 0 /dev/null 2>&1 | grep params_parse | sed -e 's/.*param\s/ 
o/' | sort =u 


If you find some parameters (such as ISO speed or other 3A settings) are missing, then it’s possible that your 
camera device is designed to use an older version of the Camera HAL than the default. You can try forcing a HAL 


vl connection by adding FORCE_HAL:=1 to env.mk in droidmedia. 





You are encouraged to set all viewfinder resolutions to match that of your device’s framebuffer. Do check for 
regressions via devel—su dconf update and reloading Camera app as you go. 


Preserve /etc/dconf/db/vendor.d/jolla-camera-hw.txt under version control just like you did 
with gstdroidcamsrc-x*x.conf above. 
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If your device supports flash torch during video recording change flashValues=[2] under [apps/ 
jolla-camera/primary/video] to flashValues=[2, 32]. 


Lastly, check other variants of /etc/dconf/db/vendor.d/jolla-camera-hw.txt throughout the 
range of existing Sailfish OS devices, or consult our developers how to obtain e.g. more valid ISO values, fo- 
cus distance, add other MegaPixel values etc. 


Ultimately you are the most welcome to improve the droid-camres tool itself by contributing upstream! 


14.4 Cellular modem 


e Ensure Android’s RIL running ps ax | grep rild (expect one or two /system/bin/rild) 
e If RIL is not running, check why it is not launched from /init*.rc scripts 


e If it’s launched, check where it fails with /usr/libexec/droid-hybris/system/bin/logcat 
-b radio 


e Errors in RIL might look like this: 


RIL[0][main] qcril_qmi_modem_power_process_bootup: ESOC node is not available 





After online search this suggests firmware loading issues on Motorola Moto G. Compare with a healthy radio 
logcat after booting back into CM, not all lines starting with E/RIL.. . will point to a root cause! 





If it’s firmware loading problem, trace all needed daemons in CM and their loading order as well as all 
mounted firmware, modem, and baseband partitions. 


Once RIL is happy, then ofono can be launched. Unmask it if it was previously masked due to causing 
reboots in Bootloops. 


If you still get no signal indicator in UI, remove SIM PIN and retry 


Also install ofono-tests package and run /usr/lib/ofono/test/list-modems 


Try to recompile latest ofono master branch from https://git.sailfishos.org/mer-core/ofono 


If everything else fails, then stop and strace a failing daemon (either RIL or ofono) from command line 
manually 


14.4.1 Phone calls don’t work (but SMS and mobile data works) 


If the calling parties cannot hear one another, then the audiosystem-passthrough-dummy=af middleware 
package is required, which should be enabled in the patterns. 


14.5 Bluetooth 


For bluetooth Sailfish OS uses BlueZ stack from linux. 
TODO: bluetooth adaptation guide. 
TODO: add detail about audio routing. 


14.6 WLAN 


Typically WLAN drivers are external kernel modules in android adaptations. To set up WLAN for such devices, a 
systemd service file needs to be created that loads the kernel module at boot. In addition to this you need to check 
that firmware files and possible HW tuning files are installed in correct locations on the filesystem. 
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Sailfish OS WLAN adaptation assumes the driver is compatible with WPA supplicant. This means the WLAN 
device driver has to support cfg80211 interface. In some cases connman (the higher level connection manager in 
Sailfish) accesses directly the WLAN driver bypassing wpa_supplicant. 


The version of currently used wpa_supplicant can be checked from here: 
https://git.sailfishos.org/mer-core/wpa_supplicant 
The version of used connman can be checked from here: 


https://git.sailfishos.org/mer-core/connman 


14.6.1 Special quirks: WLAN hotspot 


On some android WLAN drivers, the whole connectivity stack needs to be reset after WLAN hotspot use. For that 
purpose there is reset service in dsme, please see details how to set that up for your adaptation project in here: 


https://git.sailfishos.org/mer-core/dsme/commit/c377c349079b470db38ba6394 12 1b6d899004963 


14.7 NFC 


Currently there is no NFC middleware in Sailfish OS. Android HAL API support should be enough for future 
compatibility. 


14.8 GPS 


Ensure the test_gps command gets a fix after a while. 


The necessary middleware is already built for you, just add geoclue-provider-hybris package into your 
patterns. 


14.9 Audio 


For audio, Sailfish OS uses PulseAudio as the main mixer. For audio routing ohmd is used. 


TODO: Add info about audio routing configuration TODO: Add more info in general. 


14.10 Sensors 


Sailfish OS sensor support is based upon Sensor Framework at: https://git.sailfishos.org/mer-core/sensorfw 


Hybris based systems can use the hybris sensor adaptor plugins, which uses existing android libhardware sensor 
adaptations to read sensor data and control. 


It can also be configured for standard linux sysfs and evdev sensor interfaces. 


It should be configured at /etc/sensorfw/primaryuse.conf, which links to a device specific conf file. Historically 
named sensord-<BOARDNAME>.conf. You can also use any conf file by specifying it on the commandline. 


For hybris based platforms, this will be sensord-hybris.conf, and most likely will not have to be modified. 
A copy of this file is already among default configs: https://git.sailfishos.org/mer-core/sensorfw/blob/master/ 
config/sensord-hybris.conf If you do make modifications to it, add the file under SANDROID_ROOT/hybris/ 
droid-configs/sparse/etc/sensorfw/primaryuse.conf 


There are already a few device specific conf files to look at if the device needs more configuration. Example of 
mixed hybris and evdev configuration https://git.sailfishos.org/mer-core/sensorfw/blob/master/config/sensord-tbj. 
conf 
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Generally, if sensors are working on the android/hybris side, they will work in sensorfw and up to the Sailfish UL 
libhybris comes with /usr/bin/test_sensors which can list those Android sensors found. 


Above Sensor Framework is QtSensors, which requires a configuration file at /etc/xdg/QtProject/Sensors.conf 
which is supplied with the sensorfw backend plugin in QtSensors and a copy of it is already among your default 
configs. 


For Sailfish Core based systems, the QtSensors source code is at: https://github.com/mer-qt/qtsensors 


Debugging output of sensorfwd can be increased one level during runtime by sending (as root) USR1 signal like 
so: kill -USR1 pgrep sensorfwd or specified on the commandline for startup debugging. 


Sending kill -USR2 pgrep sensorfwd will output a current status report. 


14.11 Power management 


Under the hood, Sailfish OS uses the android wake locks. Typically there is no need to change anything in the 
kernel side (assuming it works fine with android) for the power management to work, as long as all the device 
drivers are working normally. 


The userspace API’s for platform applications is exposed via nemo-keepalive package. See more details here: 


https://git.sailfishos.org/mer-core/nemo-keepalive 


14.12 Watchdog 


A standard linux kernel watchdog core driver support is expected. The device node should be in /dev/watchdog. 
It should be configured with following kernel options: 


CONF IG_WATCHDOG=y 
CONF IG_WATCHDOG_CORE=y 
CONF IG_WATCHDOG_NOWAYOUT=y 





e NOTE 1: Please note that watchdog driver should disable itself during suspend. 


e NOTE 2: Normally the watchdog period is programmed automatically, but if your driver does not support 
programming the period, the default kicking period is 20 seconds. 


14.13 Touch 


Sailfish OS is compatible with standard kernel multitouch input framework drivers. Protocol A is preferred. The 
main configuration needed is to symlink the correct event device node to /dev/touchscreen. To do this the best way 
is to set up a udev rule that checks the devices with evcap script and creates the link once first valid one is found. 
See more details for evcap here: 


https://github.com/mer-hybris/evcap 
The udev rule can be put to file 
Nib/udev/rules.d/6 1-touchscreen.rules 


The reason this is not done by default is that typically driver authors mark bit varying capabilities as supported 
and there could be multiple touch controllers on a device, so the final rule is best to be written in a device specific 
configs package. 


NOTE: if you still have problems with touch, please check that lipstick environment has correct touch device 
parameter: 


cat /var/lib/environment/compositor/droid-hal-device.conf 


+ LIPSTICK_OPTIONS should have “-plugin evdevtouch:/dev/touchscreen” 
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14.13.1 Special feature: double tap to wake up 


Sailfish OS supports waking up the device from suspend (unblanking the screen) via double tap gesture 
to the touchscreen. The touchscreen driver should either emulate KEY_POWER press / release or post a 
EV_MSC/MSC_GESTURE event with value 0x4 when double tap gesture is detected when waking up from 
suspend. 


In order to avoid excess power drain when device is in pocket facing users skin, some sysfs should be exported 
to allow disabling the touch screen. The feature requires that the device has a working proximity sensor that can 
wake up the system when it is suspended (to be able to update touch screen state according to need). To configure 
MCE that handles this see MCE configuration 
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CHAPTER 
FIFTEEN 


MIDDLEWARE 


This chapter contains some background information about the middleware parts that are part of the Hardware 
Adapation. Using this info, it should be possible to customize and build the middleware parts for a given device. 


15.1 MCE libhybris Plugin 


TODO 


15.2 MCE configuration 


/etc/mce/60-doubletap-jolla.ini 


Configures the touchscreen kernel driver sysfs that can be used to disable and enable double tap to wake up feature. 
Example of it’s content: 


# Configuration for doubletap wakeup plugin 

[DoubleTap] 

# Path to doubletap wakeup control file 
ControlPath=/sys/bus/i2c/drivers/touch_synaptics/3-0020/double_tap_enable 
# Value to write when enabling doubletap wakeups 

EnableValue=1 

# Value to write when Disabling doubletap wakeups 

DisableValue=0 





TODO: 

/etc/mce/60-mce-cpu-scaling-governor.ini 
/etc/mce/60-mce-display-blank-timeout.conf 
/etc/mce/60-mce-display-brightness.conf 
/etc/mce/60-mce-possible-display-dim-timeouts.conf 


/etc/mce/60-memnotify-jolla.conf 


15.3 Configuring haptics 


Sailfish OS has 2 kinds of feedback methods: 
1. NGFD - Non-graphical feedback framework ffmemless plugin 
2. QtFeedback - QtFeedback with direct ffmemless backend 
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The NGFD plugin is for providing feedback for events and alarms, while QtFeedback is used for minimum latency 
haptics and for 3rd party applications. 


Both of these have their own default .ini configuration files with the default effects for basic use. The default 
configurations can be overridden with device specific .ini files in your adaptation project’s config package. The 
default config files can be seen in: 


e NGED: /usr/share/ngfd/plugins.d/ffmemless.ini 
e QtFeedback: /usr/lib/qt5/plugins/feedback/ffmemless.ini 


The default configuration files can be  over-ridden with setting environment variables 
NGF_FFMEMLESS_SETTINGS (ngfd) and FF_MEMLESS_SETTINGS (qtfeedback), that point to device 
specifc configuration files. 


To set the environment variables add environment config file to your config package that installs to (NOTE: 
Replace “DEVICE” with your device’s name. E.g. mako, hammerhead, etc.): 


/var/lib/environment/nemo/60-DEVICE-vibra.conf 
And that file should contain 2 lines: 


FF_MEMLESS_SETTINGS=/usr/lib/qt5/plugins/feedback/qtfeedback-DEVICE.ini 
NGF_FFMEMLESS_SETTINGS=/usr/share/ngfd/plugins.d/ngf-vibra-DEVICE.ini 




















Now you can use those 2 files to tune force feedback effects suitable specifically for your device. For template to 
start making your own configuration files, just copy-paste the ngfd ffmemless.ini and Qtfeedback ffmemless.ini 
default config files as the device specific files and then edit only needed bits. 


The reason we have possibility for device specific effects is that hardware mechanics and the vibra engines differ 
greatly device-by-device, and single settings will not give good effect on all devices. 


+ At minimum, you should ALWAYS tune at least KEYPAD effect in qtfeedback-DEVICE.ini for every 
device separately to make the VKB haptic feel good and punctual. 


Good guideline for VKB haptic is that 1t should be as short as possible, and vibrate at the resonance frequency of 
the device mechanics when vibra engine reaches top magnitude of the vibra effect. It should not feel like vibration, 
but like a single kick. 


15.4 Non-Graphical Feedback Daemon 
The Non-Graphical Feedback Daemon provides combined audio, haptic, and LED feedback for system events and 
alarms. These events include such things as ring tones, message tones, clock alarms, email notifications, etc. 


e https://git.sailfishos.org/mer-core/ngfd 


TODO: add more detail about configuring NGFD. 


15.5 Non-Graphic Feedback Daemon PulseAudio Plugin 


TODO 


15.6 Non-Graphic Feedback Daemon Droid ffmemless Plugin 


This is the main plugin handling vibra feedback for Sailfish OS. See Configuring haptics for more details. 
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15.7 Non-Graphic Feedback Daemon Droid Vibrator Plugin 


This is a secondary vibra plugin for demoing and quick ports. It works out of the box with android timed output 
drivers. The feature set is reduced compared to ffmemless plugin. 


TODO 


15.8 PulseAudio Droid Modules 


TODO - more information about how PA works 


15.9 Qt5 QtFeedback Droid Vibrator Plugin 


TODO 


15.10 Qt5 Hardware Composer QPA 


This Qt Platform Abstraction plugin makes use of the libhardware hwcomposer API to send rendered frames from 
the Wayland Compositor to the actual framebuffer. While for some older devices, just flipping the fbdev was 
enough, more recent devices actually require using hwcomposer to request flipping and for vsync integration. 


The important environment variables are: 


e EGL_PLATFORM: For the Wayland Compositor, this needs to be set to fodev on devices with older hw- 
composer versions, and to hwcomposer for hwcomposer version 1.1 and newer. For best results, first try 
fbdev, and if it doesn’t work, try hwcomposer instead. For the Wayland Clients, this always needs to be 
set to wayland. 





OT_OPA PLATFORM: For the Wayland Compositor, this needs to be set to hwcomposer to use the plugin. 
Previously, eglfs was used, but the hwcomposer module replaces the old plugin on Sailfish OS on 
Droid. For Wayland Clients, this always needs to be set to wayland. 





When starting up an application (e.g. the Wayland Compositor, Lipstick), the systemd journal (Journalct 1 
—fa as user root) will show some details about the detected screen metrics, which will come from the framebuffer 
device: 








HwComposerScreenInfo:251 - EGLFS: Screen Info 
HwComposerScreenInfo:252 - -— Physical size: QOSizeF (57, 100) 
HwComposerScreenInfo:253 Screen size: QSize(540, 960) 
HwComposerScreenInfo:254 Screen depth: 32 





Also, it will print information about the hwcomposer module and the device. In this specific case, the hwcomposer 
version is 0.3: 


== hwcomposer module == 

* Address: 0x40132000 

* Module API Version: 2 

* HAL API Version: 0 

* Identifier: hwcomposer 

* Name: Qualcomm Hardware Composer Module 
* Author: CodeAurora Forum 

== hwcomposer module == 

== hwcomposer device == 

* Version: 3 (interpreted as 30001) 
* Module: 0x40132000 

== hwcomposer device == 
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The source tree contains different implementations of hwcomposer backends, each one for a different hwcomposer 
API version (see hwcomposer/hwcomposer_backend.cpp). Based on that detection, one of the existing 
implementations is used. Right now, the following implementations exist: 


hwcomposer_backend_v0: Version 0.x (e.g. 0.3) of the hwcomposer API. It can handle swapping of an EGL 
surface to the display, doesn’t use any additional hardware layers at the moment and can support switching 
the screen off. The VSync period is queried from the hwcomposer device, but it will fall back to 60 Hz if 
the information cannot be determined via the libhardware APIs. (EGL_PLATFORM=fbdev) 





hwcomposer_backend_v10: Version 1.0 of the hwcomposer API. It supports one display device, handles 
VSync explicitly and uses a single hardware layer that will be drawn via EGL (and not composed via 
hwcomposer). Swapping is done by waiting for VSync and uses libsync-based synchronization of posting 
buffers. Switching the screen off is also supported, and sleeping the screen disables VSync events. Also, the 
same VSync period algorithm is used (try to query from libhardware, fall back to 60 Hz if detection fails). 
(EGL_PLATFORM=fbdev) 





hwcomposer_backend_v11]: Version 1.1, 1.2, 1.3, 1.4, and 1.5 of the hwcomposer API. Versions higher 
or equal than 1.3 only support physical displays, whereas 1.1 and 1.2 support also virtual displays. This 
requires libsync and hwcomposer-egl from libhybris. Most of the hwcomposer 1.0 API properties apply, 
with the exception that frame posting and synchronization happens with the help of libhybris’ hwcomposer 
EGL platform. (EGL_PLATFORM=hwcomposer) 





Instead of running the Wayland Compositor (lipstick) on top of the hwcomposer QPA plugin, one can also run all 
other Qt 5-based applications, but the application can only open a single window (multiple windows are not sup- 
ported, and will cause an application abort). For multiple windows, Wayland is used. This means that for testing, it 
is possible to run a simple, single-window Qt 5 application on the framebuffer (without any Wayland Compositor 
in between) by setting the environment variables EGL_PLATFORM and OT_OPA_PLATFORM according to the 
above. 





15.11 SensorFW Qt 5 / libhybris Plugin 


TODO 


15.12 Build HA Middleware Packages 


rem/dhd/helpers/build_packages. sh now is taking care of builds/rebuilds/local repo preparation and 
patterns. 


15.12.1 All other packages 


Please compile any other required packages should a build/mic process indicate a dependency on them. Feel free 
to add/remove those packages to/from patterns to suit your port's needs. 


Follow the exact same compilation approach as with above packages. Known packages are: 


https://github.com/mer-hybris/unblank-restart-sensors - needed only by mako 
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CHAPTER 
SIXTEEN 


LIST OF REPOSITORIES 


droid-hal-$DEVICE Contains RPM packaging and conversion scripts for converting the results of the Android 
HAL build process to RPM packages and systemd configuration files. 


hybris-boot Script run during Android HAL build that will combine the kernel and a custom initrd to 
hybris-boot.img and hybris-recovery.img. Those are used to boot a device into Sailfish OS 
and for development purposes. 


hybris-installer Combines the hybris-boot output and the root filesystem into a .zip file that can be flashed 
via Android Recovery. 


libhybris Library to allow access to Bionic-based libraries from a glibc-based host system (e.g. hwcomposer, 
EGL, GLESv?, ..). 


qt5-qpa-hwcomposer-plugin Qt 5 Platform Abstraction Plugin that allows fullscreen rendering to the Droid- 
based hardware abstraction. It utilizes libhybris and the Android hwcomposer module. 


mer-kernel-check A script that checks if the kernel configuration is suitable for Sailfish OS. Some features must 
be enabled, as they are needed on Sailfish OS (e.g. to support systema), other features must be disabled, 
as they conflict with Sailfish OS (e.g. CONFIG_ANDROID_PARANOID_NETWORK) at the moment. 
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CHAPTER 
SEVENTEEN 


PACKAGE NAMING POLICY 


For consistency, certain hardware adaptation / middleware plugin packages have to be named after a certain pat- 


tern. 











As in the other chapters of this guide, SDEVICE should be replaced with the device codename (e.g. mako for 
Nexus 4), and the asterisk (*) is used as wildcard / placeholder. 





17.1 List of naming rules 














Packages that are arch-specific (e.g. aarch64), device-specific and contain SDEVICE in their name: 


e The arch-specific HAL RPMs (built from droid-hal-device) should be named droid-hal- 














$DEVICE (e.g. droid-hal-mako, droid-hal-mako-devel, droid-hal-mako-img-boot, 
droid-hal-mako-kernel, droid-hal-mako-kernel-modules, 
droid-hal-mako-kickstart-configuration, droid-hal-mako-patterns, 











droid-hal-mako-policy-settings and droid-hal-mako-pulseaudio-settings) 


The package containing kickstart files for mic should be named ssu-kickstarts-$DEVICE (e.g. 
ssu-kickstarts-mako) 





Package that are arch-independent (noarch), device-specific and contain SDEVICE in their name: 


Packages that are arch-specific (e.g. aarch64), device-specific, but do not contain SDEVICE: 











The arch-independent HAL RPMs (built from  «kroid-hal-device) should be 
named: droid-hal-$DEVICE-* (e.g. droid-hal-mako-img-recovery and 
droid-hal-mako-sailfish-config) 





The SensorFW libhybris plugin configuration should be named hybris-libsensorfw-qt5-configs 
(hybris-libsensorfw-qt5-configs) 














RPMs built from libhybris should be named libhybris-* (e.g. libhybris-1ibEGL) 








Plugins for the non-graphic feedback daemon should be named  ngfd-plugin-* (e.g. 
ngfd-plugin-droid-vibrator); as well as their Qt plugin qt5-feedback-haptics-droid-vibrator 
(qt 5-feedback-haptics-—droid-vibrator) 





The QPA hwcomposer plugin should be named qt5-qpa-hwcomposer-plugin 
(qt 5-qpa-hwcomposer-plugin) 


The PulseAudio support modules should be named pulseaudio-modules-droid 
(pulseaudio-modules-droid) 





The GStreamer plugins should be named libgstreamer0.10-* and/or gstramer0.10-* (e.g. 
libgstreamer0.10-gralloc, libgstreamer0.1l0-nativebuffer, gstreamer0. 
10-omx, gstreamer0.10-droideglsink and gstreamer0.10-droidcamsrc) 








The SensorFW libhybris plugin should be named hybris-libsensorfw-qt5 
(hybris-libsensorfw-qt5) 
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17.2 List of Provides 


e droid-hal-$DEVICE-* provides droid-hal-* (e.g. droid-hal-SDEVICE 











pulseaudio-settings 











provides droid-hal-pulseaudio-settings) 


17.3 TODO 


The above “rules” are the current state of our hardware adaptation. Here are some things that should be improved 


there: 


independent (noarch) instead 


ing schemes there 


Some arch-specific packages contain arch-independent config files or binary blobs - make them arch- 


Unify the GStreamer plugin naming (either libgstreamer0.10-* or gstreamer0.10-*) to not have two nam- 


The PulseAudio settings package usually is called pulseaudio-settings-$DEVICE (we currently have 


droid-hal-$DEVICE-pulseaudio-settings, maybe this can be implemented as a Provides :?) 


adaptations we use kmod-xyz-$DEVICE 


hardware adaptations we use jolla-recovery-$DEVICE 


The Linux kernel modules are in droid-hal-$DEVICE-kernel-modules at the moment, in other hardware 


The recovery partition in the image at the moment is droid-hal-$DEVICE-img-recovery, but for other 
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CHAPTER 
EIGHTEEN 


LICENSE 


Creative Commons Legal Code 


Attribution-NonCommercial-ShareAlike 3.0 Unported 


CREATIVE COMMONS CORPORATION IS NOT A LAW FIRM AND DOES NOT PROVIDE 
LEGAL SERVICES. DISTRIBUTION OF THIS LICENSE DOES NOT CREATE AN ATTORNEY- 
CLIENT RELATIONSHIP. CREATIVE COMMONS PROVIDES THIS INFORMATION ON AN 
“AS-IS” BASIS. CREATIVE COMMONS MAKES NO WARRANTIES REGARDING THE IN- 
FORMATION PROVIDED, AND DISCLAIMS LIABILITY FOR DAMAGES RESULTING FROM 
ITS USE. 


License 


THE WORK (AS DEFINED BELOW) IS PROVIDED UNDER THE TERMS OF THIS CREATIVE COMMONS 
PUBLIC LICENSE (“CCPL” OR “LICENSE”). THE WORK IS PROTECTED BY COPYRIGHT AND/OR 
OTHER APPLICABLE LAW. ANY USE OF THE WORK OTHER THAN AS AUTHORIZED UNDER THIS 
LICENSE OR COPYRIGHT LAW IS PROHIBITED. 


BY EXERCISING ANY RIGHTS TO THE WORK PROVIDED HERE, YOU ACCEPT AND AGREE TO BE 
BOUND BY THE TERMS OF THIS LICENSE. TO THE EXTENT THIS LICENSE MAY BE CONSIDERED 
TO BE A CONTRACT, THE LICENSOR GRANTS YOU THE RIGHTS CONTAINED HERE IN CONSIDER- 
ATION OF YOUR ACCEPTANCE OF SUCH TERMS AND CONDITIONS. 


1. 


a. 


Definitions 


“Adaptation” means a work based upon the Work, or upon the Work and other pre-existing works, such as 
a translation, adaptation, derivative work, arrangement of music or other alterations of a literary or artistic 
work, or phonogram or performance and includes cinematographic adaptations or any other form in which 
the Work may be recast, transformed, or adapted including in any form recognizably derived from the 
original, except that a work that constitutes a Collection will not be considered an Adaptation for the purpose 
of this License. For the avoidance of doubt, where the Work is a musical work, performance or phonogram, 
the synchronization of the Work in timed-relation with a moving image (“synching”) will be considered an 
Adaptation for the purpose of this License. 


. “Collection” means a collection of literary or artistic works, such as encyclopedias and anthologies, or 


performances, phonograms or broadcasts, or other works or subject matter other than works listed in Sec- 
tion 1(g) below, which, by reason of the selection and arrangement of their contents, constitute intellectual 
creations, in which the Work is included in its entirety in unmodified form along with one or more other 
contributions, each constituting separate and independent works in themselves, which together are assem- 
bled into a collective whole. A work that constitutes a Collection will not be considered an Adaptation (as 
defined above) for the purposes of this License. 


. “Distribute” means to make available to the public the original and copies of the Work or Adaptation, as 


appropriate, through sale or other transfer of ownership. 


. “License Elements” means the following high-level license attributes as selected by Licensor and indicated 


in the title of this License: Attribution, Noncommercial, ShareAlike. 


. “Licensor” means the individual, individuals, entity or entities that offer(s) the Work under the terms of this 


License. 
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f. “Original Author” means, in the case of a literary or artistic work, the individual, individuals, entity or 
entities who created the Work or if no individual or entity can be identified, the publisher; and in addition 
(i) in the case of a performance the actors, singers, musicians, dancers, and other persons who act, sing, 
deliver, declaim, play in, interpret or otherwise perform literary or artistic works or expressions of folklore; 
(ii) in the case of a phonogram the producer being the person or legal entity who first fixes the sounds 
of a performance or other sounds; and, (iii) in the case of broadcasts, the organization that transmits the 
broadcast. 


g. “Work” means the literary and/or artistic work offered under the terms of this License including without 
limitation any production in the literary, scientific and artistic domain, whatever may be the mode or form 
of its expression including digital form, such as a book, pamphlet and other writing; a lecture, address, 
sermon or other work of the same nature; a dramatic or dramatico-musical work; a choreographic work 
or entertainment in dumb show; a musical composition with or without words; a cinematographic work 
to which are assimilated works expressed by a process analogous to cinematography; a work of drawing, 
painting, architecture, sculpture, engraving or lithography; a photographic work to which are assimilated 
works expressed by a process analogous to photography; a work of applied art; an illustration, map, plan, 
sketch or three-dimensional work relative to geography, topography, architecture or science; a performance; 
a broadcast; a phonogram; a compilation of data to the extent it is protected as a copyrightable work; or 
a work performed by a variety or circus performer to the extent it is not otherwise considered a literary or 
artistic work. 


h. “You” means an individual or entity exercising rights under this License who has not previously violated the 
terms of this License with respect to the Work, or who has received express permission from the Licensor 
to exercise rights under this License despite a previous violation. 


i. “Publicly Perform” means to perform public recitations of the Work and to communicate to the public 
those public recitations, by any means or process, including by wire or wireless means or public digital 
performances; to make available to the public Works in such a way that members of the public may access 
these Works from a place and at a place individually chosen by them; to perform the Work to the public by 
any means or process and the communication to the public of the performances of the Work, including by 
public digital performance; to broadcast and rebroadcast the Work by any means including signs, sounds or 
images. 


j. “Reproduce” means to make copies of the Work by any means including without limitation by sound or 
visual recordings and the right of fixation and reproducing fixations of the Work, including storage of a 
protected performance or phonogram in digital form or other electronic medium. 


2. Fair Dealing Rights. Nothing in this License is intended to reduce, limit, or restrict any uses free from copyright 
or rights arising from limitations or exceptions that are provided for in connection with the copyright protection 
under copyright law or other applicable laws. 


3. License Grant. Subject to the terms and conditions of this License, Licensor hereby grants You a worldwide, 
royalty-free, non-exclusive, perpetual (for the duration of the applicable copyright) license to exercise the rights 
in the Work as stated below: 


a. to Reproduce the Work, to incorporate the Work into one or more Collections, and to Reproduce the Work 
as incorporated in the Collections; 


b. to create and Reproduce Adaptations provided that any such Adaptation, including any translation in any 
medium, takes reasonable steps to clearly label, demarcate or otherwise identify that changes were made 
to the original Work. For example, a translation could be marked “The original work was translated from 
English to Spanish,” or a modification could indicate “The original work has been modified.’; 


c. to Distribute and Publicly Perform the Work including as incorporated in Collections; and, 
d. to Distribute and Publicly Perform Adaptations. 


The above rights may be exercised in all media and formats whether now known or hereafter devised. The above 
rights include the right to make such modifications as are technically necessary to exercise the rights in other media 
and formats. Subject to Section 8(f), all rights not expressly granted by Licensor are hereby reserved, including 
but not limited to the rights described in Section 4(e). 


4. Restrictions. The license granted in Section 3 above is expressly made subject to and limited by the following 
restrictions: 
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a. You may Distribute or Publicly Perform the Work only under the terms of this License. You 


must include a copy of, or the Uniform Resource Identifier (URI) for, this License with every 
copy of the Work You Distribute or Publicly Perform. You may not offer or impose any terms 
on the Work that restrict the terms of this License or the ability of the recipient of the Work 
to exercise the rights granted to that recipient under the terms of the License. You may not 
sublicense the Work. You must keep intact all notices that refer to this License and to the 
disclaimer of warranties with every copy of the Work You Distribute or Publicly Perform. When 
You Distribute or Publicly Perform the Work, You may not impose any effective technological 
measures on the Work that restrict the ability of a recipient of the Work from You to exercise 
the rights granted to that recipient under the terms of the License. This Section 4(a) applies to 
the Work as incorporated in a Collection, but this does not require the Collection apart from the 
Work itself to be made subject to the terms of this License. If You create a Collection, upon 
notice from any Licensor You must, to the extent practicable, remove from the Collection any 
credit as required by Section 4(d), as requested. If You create an Adaptation, upon notice from 
any Licensor You must, to the extent practicable, remove from the Adaptation any credit as 
required by Section 4(d), as requested. 


. You may Distribute or Publicly Perform an Adaptation only under: (1) the terms of this License; 


(11) a later version of this License with the same License Elements as this License; (iii) a Cre- 
ative Commons jurisdiction license (either this or a later license version) that contains the same 
License Elements as this License (e.g., Attribution-NonCommercial-ShareAlike 3.0 US) (“Ap- 
plicable License”). You must include a copy of, or the URI, for Applicable License with every 
copy of each Adaptation You Distribute or Publicly Perform. You may not offer or impose any 
terms on the Adaptation that restrict the terms of the Applicable License or the ability of the 
recipient of the Adaptation to exercise the rights granted to that recipient under the terms of the 
Applicable License. You must keep intact all notices that refer to the Applicable License and 
to the disclaimer of warranties with every copy of the Work as included in the Adaptation You 
Distribute or Publicly Perform. When You Distribute or Publicly Perform the Adaptation, You 
may not impose any effective technological measures on the Adaptation that restrict the ability 
of a recipient of the Adaptation from You to exercise the rights granted to that recipient under 
the terms of the Applicable License. This Section 4(b) applies to the Adaptation as incorporated 
in a Collection, but this does not require the Collection apart from the Adaptation itself to be 
made subject to the terms of the Applicable License. 


. You may not exercise any of the rights granted to You in Section 3 above in any manner that is 


primarily intended for or directed toward commercial advantage or private monetary compensa- 
tion. The exchange of the Work for other copyrighted works by means of digital file-sharing or 
otherwise shall not be considered to be intended for or directed toward commercial advantage 
or private monetary compensation, provided there is no payment of any monetary compensation 
in con-nection with the exchange of copyrighted works. 


. If You Distribute, or Publicly Perform the Work or any Adaptations or Collections, You must, 


unless a request has been made pursuant to Section 4(a), keep intact all copyright notices for 
the Work and provide, reasonable to the medium or means You are utilizing: (i) the name of the 
Original Author (or pseudonym, if applicable) if supplied, and/or if the Original Author and/or 
Licensor designate another party or parties (e.g., a sponsor institute, publishing entity, journal) 
for attribution (“Attribution Parties”) in Licensor’s copyright notice, terms of service or by other 
reasonable means, the name of such party or parties; (ii) the title of the Work if supplied; (iii) to 
the extent reasonably practicable, the URL if any, that Licensor specifies to be associated with 
the Work, unless such URI does not refer to the copyright notice or licensing information for the 
Work; and, (iv) consistent with Section 3(b), in the case of an Adaptation, a credit identifying the 
use of the Work in the Adaptation (e.g., “French translation of the Work by Original Author,” or 
“Screenplay based on original Work by Original Author”). The credit required by this Section 
4(d) may be implemented in any reasonable manner; provided, however, that in the case of a 
Adaptation or Collection, at a minimum such credit will appear, if a credit for all contributing 
authors of the Adaptation or Collection appears, then as part of these credits and in a manner 
at least as prominent as the credits for the other contributing authors. For the avoidance of 
doubt, You may only use the credit required by this Section for the purpose of attribution in the 
manner set out above and, by exercising Your rights under this License, You may not implicitly 
or explicitly assert or imply any connection with, sponsorship or endorsement by the Original 
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Author, Licensor and/or Attribution Parties, as appropriate, of You or Your use of the Work, 
without the separate, express prior written permission of the Original Author, Licensor and/or 
Attribution Parties. 


e. For the avoidance of doubt: 


i. Non-waivable Compulsory License Schemes. In those jurisdictions in which the right to 
collect royalties through any statutory or compulsory licensing scheme cannot be waived, 
the Licensor reserves the exclusive right to collect such royalties for any exercise by You 
of the rights granted under this License; 


ii. Waivable Compulsory License Schemes. In those jurisdictions in which the right to collect 
royalties through any statutory or compulsory licensing scheme can be waived, the Licensor 
reserves the exclusive right to collect such royalties for any exercise by You of the rights 
granted under this License if Your exercise of such rights is for a purpose or use which is 
otherwise than noncommercial as permitted under Section 4(c) and otherwise waives the 
right to collect royalties through any statutory or compulsory licensing scheme; and, 


111. Voluntary License Schemes. The Licensor reserves the right to collect royalties, whether indi- 
vidually or, in the event that the Licensor is a member of a collecting society that administers 
voluntary licensing schemes, via that society, from any exercise by You of the rights granted un- 
der this License that is for a purpose or use which is otherwise than noncommercial as permitted 
under Section 4(c). 


f. Except as otherwise agreed in writing by the Licensor or as may be otherwise permitted by 
applicable law, if You Reproduce, Distribute or Publicly Perform the Work either by itself or 
as part of any Adaptations or Collections, You must not distort, mutilate, modify or take other 
derogatory action in relation to the Work which would be prejudicial to the Original Author’s 
honor or reputation. Licensor agrees that in those jurisdictions (e.g. Japan), in which any 
exercise of the right granted in Section 3(b) of this License (the right to make Adaptations) would 
be deemed to be a distortion, mutilation, modification or other derogatory action prejudicial to 
the Original Author’s honor and reputation, the Licensor will waive or not assert, as appropriate, 
this Section, to the fullest extent permitted by the applicable national law, to enable You to 
reasonably exercise Your right under Section 3(b) of this License (right to make Adaptations) 
but not otherwise. 


5. Representations, Warranties and Disclaimer 


UNLESS OTHERWISE MUTUALLY AGREED TO BY THE PARTIES IN WRITING AND TO THE FULLEST 
EXTENT PERMITTED BY APPLICABLE LAW, LICENSOR OFFERS THE WORK AS-IS AND MAKES 
NO REPRESENTATIONS OR WARRANTIES OF ANY KIND CONCERNING THE WORK, EXPRESS, IM- 
PLIED, STATUTORY OR OTHERWISE, INCLUDING, WITHOUT LIMITATION, WARRANTIES OF TITLE, 
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, NONINFRINGEMENT, OR THE AB- 
SENCE OF LATENT OR OTHER DEFECTS, ACCURACY, OR THE PRESENCE OF ABSENCE OF ERRORS, 
WHETHER OR NOT DISCOVERABLE. SOME JURISDICTIONS DO NOT ALLOW THE EXCLUSION OF 
IMPLIED WARRANTIES, SO THIS EXCLUSION MAY NOT APPLY TO YOU. 


6. Limitation on Liability. EXCEPT TO THE EXTENT REQUIRED BY APPLICABLE LAW, IN NO EVENT 
WILL LICENSOR BE LIABLE TO YOU ON ANY LEGAL THEORY FOR ANY SPECIAL, INCIDENTAL, 
CONSEQUENTIAL, PUNITIVE OR EXEMPLARY DAMAGES ARISING OUT OF THIS LICENSE OR THE 
USE OF THE WORK, EVEN IF LICENSOR HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAM- 
AGES. 


7. Termination 


a. This License and the rights granted hereunder will terminate automatically upon any breach by You of the 
terms of this License. Individuals or entities who have received Adaptations or Collections from You under 
this License, however, will not have their licenses terminated provided such individuals or entities remain in 
full compliance with those licenses. Sections 1, 2, 5, 6, 7, and 8 will survive any termination of this License. 


b. Subject to the above terms and conditions, the license granted here is perpetual (for the duration of the 
applicable copyright in the Work). Notwithstanding the above, Licensor reserves the right to release the 
Work under different license terms or to stop distributing the Work at any time; provided, however that any 
such election will not serve to withdraw this License (or any other license that has been, or is required to 
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be, granted under the terms of this License), and this License will continue in full force and effect unless 
terminated as stated above. 


8. Miscellaneous 


a. Each time You Distribute or Publicly Perform the Work or a Collection, the Licensor offers to the recipient 
a license to the Work on the same terms and conditions as the license granted to You under this License. 


b. Each time You Distribute or Publicly Perform an Adaptation, Licensor offers to the recipient a license to the 
original Work on the same terms and conditions as the license granted to You under this License. 


c. If any provision of this License is invalid or unenforceable under applicable law, it shall not affect the 
validity or enforceability of the remainder of the terms of this License, and without further action by the 
parties to this agreement, such provision shall be reformed to the minimum extent necessary to make such 
provision valid and enforceable. 


d. No term or provision of this License shall be deemed waived and no breach consented to unless such waiver 
or consent shall be in writing and signed by the party to be charged with such waiver or consent. 


e. This License constitutes the entire agreement between the parties with respect to the Work licensed here. 
There are no understandings, agreements or representations with respect to the Work not specified here. 
Licensor shall not be bound by any additional provisions that may appear in any communication from You. 
This License may not be modified without the mutual written agreement of the Licensor and You. 


f. The rights granted under, and the subject matter referenced, in this License were drafted utilizing the termi- 
nology of the Berne Convention for the Protection of Literary and Artistic Works (as amended on September 
28, 1979), the Rome Convention of 1961, the WIPO Copyright Treaty of 1996, the WIPO Performances and 
Phonograms Treaty of 1996 and the Universal Copyright Convention (as revised on July 24, 1971). These 
rights and subject matter take effect in the relevant jurisdiction in which the License terms are sought to 
be enforced according to the corresponding provisions of the implementation of those treaty provisions in 
the applicable national law. If the standard suite of rights granted under applicable copyright law includes 
additional rights not granted under this License, such additional rights are deemed to be included in the 
License; this License is not intended to restrict the license of any rights under applicable law. 


Creative Commons Notice 


Creative Commons is not a party to this License, and makes no warranty whatsoever in connection 
with the Work. Creative Commons will not be liable to You or any party on any legal theory for any 
damages whatsoever, including without limitation any general, special, incidental or consequential 
damages arising in connection to this license. Notwithstanding the foregoing two (2) sentences, if 
Creative Commons has expressly identified itself as the Licensor hereunder, it shall have all rights 
and obligations of Licensor. 


Except for the limited purpose of indicating to the public that the Work is licensed under the CCPL, 
Creative Commons does not authorize the use by either party of the trademark “Creative Commons” 
or any related trademark or logo of Creative Commons without the prior written consent of Creative 
Commons. Any permitted use will be in compliance with Creative Commons’ then-current trademark 
usage guidelines, as may be published on its website or otherwise made available upon request from 
time to time. For the avoidance of doubt, this trademark restriction does not form part of this License. 


Creative Commons may be contacted at http://creativecommons.org/. 
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